0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 36 2e 31 2e ersion 3.7.16.1.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 gle large file,
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 the entire code
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 can be compiled
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 ny compilers to
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 that would not
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e tely. Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 s compiled as a
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 ompile SQLite.
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 ibrary. (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 header file at
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 ile. Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 ite3.h" to find
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 the start.** of
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 le.) Additional
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 QLite with your
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 e. The code for
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 separate file.
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 SQLITE_PRIVATE
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 static.#endif.#i
0550: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
0560: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
0570: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a _API.#endif./***
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 *********** Begi
0590: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 n file sqliteInt
05a0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
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 2a 2a 2a 2f 0a 2f 2a 0a 2a **********/./*.*
05d0: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 * 2001 September
05e0: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 15.**.** The au
05f0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
0600: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
0610: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
0620: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
0630: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
0640: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
0650: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
0660: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
0670: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
0680: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
0690: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
06a0: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
06b0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
06c0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
06d0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
06e0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
06f0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
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 2a ****************
0740: 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 **.** Internal i
0750: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 nterface definit
0760: 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e ions for SQLite.
0770: 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f .**.*/.#ifndef _
0780: 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 SQLITEINT_H_.#de
0790: 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f fine _SQLITEINT_
07a0: 48 5f 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 H_../*.** These
07b0: 23 64 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 #defines should
07c0: 65 6e 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 enable >2GB file
07d0: 20 73 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 support on POSI
07e0: 58 20 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 X if the.** unde
07f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
0800: 20 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 system supports
0810: 20 69 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 it. If the OS
0820: 6c 61 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 lacks.** large f
0830: 69 6c 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 ile support, or
0840: 69 66 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e if the OS is win
0850: 64 6f 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 dows, these shou
0860: 6c 64 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a ld be no-ops..**
0870: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 .** Ticket #2739
0880: 3a 20 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c : The _LARGEFIL
0890: 45 5f 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d E_SOURCE macro m
08a0: 75 73 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 ust appear befor
08b0: 65 20 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 e any.** system
08c0: 23 69 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 #includes. Henc
08d0: 65 2c 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 e, this block of
08e0: 20 63 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 code must be th
08f0: 65 20 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 e very first.**
0900: 63 6f 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 code in all sour
0910: 63 65 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 ce files..**.**
0920: 4c 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f Large file suppo
0930: 72 74 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c rt can be disabl
0940: 65 64 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 ed using the -DS
0950: 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 QLITE_DISABLE_LF
0960: 53 20 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 S switch.** on t
0970: 68 65 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d he compiler comm
0980: 61 6e 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 and line. This
0990: 69 73 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 is necessary if
09a0: 79 6f 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e you are compilin
09b0: 67 0a 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 g.** on a recent
09c0: 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 machine (ex: Re
09d0: 64 20 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 d Hat 7.2) but y
09e0: 6f 75 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 ou want your cod
09f0: 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 e to work.** on
0a00: 61 6e 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 an older machine
0a10: 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e (ex: Red Hat 6.
0a20: 30 29 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 0). If you comp
0a30: 69 6c 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 ile on Red Hat 7
0a40: 2e 32 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 .2.** without th
0a50: 69 73 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 is option, LFS i
0a60: 73 20 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c s enable. But L
0a70: 46 53 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 FS does not exis
0a80: 74 20 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a t in the kernel.
0a90: 2a 2a 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e ** in Red Hat 6.
0aa0: 30 2c 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 0, so the code w
0ab0: 6f 6e 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 on't work. Henc
0ac0: 65 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 e, for maximum b
0ad0: 69 6e 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 inary.** portabi
0ae0: 6c 69 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 lity you should
0af0: 6f 6d 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 omit LFS..**.**
0b00: 53 69 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 Similar is true
0b10: 66 6f 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c for Mac OS X. L
0b20: 46 53 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f FS is only suppo
0b30: 72 74 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 rted on Mac OS X
0b40: 20 39 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 9 and later..*/
0b50: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
0b60: 44 49 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 DISABLE_LFS.# de
0b70: 66 69 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 fine _LARGE_FILE
0b80: 20 20 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 1.# ifnde
0b90: 66 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 f _FILE_OFFSET_B
0ba0: 49 54 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f ITS.# define _
0bb0: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 FILE_OFFSET_BITS
0bc0: 20 36 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 64.# endif.# de
0bd0: 66 69 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f fine _LARGEFILE_
0be0: 53 4f 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a SOURCE 1.#endif.
0bf0: 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 ./*.** Include t
0c00: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
0c10: 20 68 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 header output b
0c20: 79 20 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 y 'configure' if
0c30: 20 77 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 we're using the
0c40: 0a 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 .** autoconf-bas
0c50: 65 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 ed build.*/.#ifd
0c60: 65 66 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f ef _HAVE_SQLITE_
0c70: 43 4f 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 CONFIG_H.#includ
0c80: 65 20 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e e "config.h".#en
0c90: 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a dif../**********
0ca0: 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c **** Include sql
0cb0: 69 74 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 iteLimit.h in th
0cc0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 e middle of sqli
0cd0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a teInt.h ********
0ce0: 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***/./**********
0cf0: 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 **** Begin file
0d00: 73 71 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a sqliteLimit.h **
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d30: 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 ***/./*.** 2007
0d40: 4d 61 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 May 7.**.** The
0d50: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 author disclaims
0d60: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 copyright to th
0d70: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
0d80: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 In place of.**
0d90: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 a legal notice,
0da0: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 here is a blessi
0db0: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 ng:.**.** May
0dc0: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 you do good and
0dd0: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 not evil..**
0de0: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f May you find fo
0df0: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f rgiveness for yo
0e00: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 urself and forgi
0e10: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 ve others..**
0e20: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 May you share f
0e30: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b reely, never tak
0e40: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f ing more than yo
0e50: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a u give..**.*****
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ea0: 2a 2a 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 ****.** .** This
0eb0: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 file defines va
0ec0: 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 rious limits of
0ed0: 77 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 what SQLite can
0ee0: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a process..*/../*.
0ef0: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c ** The maximum l
0f00: 65 6e 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 ength of a TEXT
0f10: 6f 72 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 or BLOB in bytes
0f20: 2e 20 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a . This also.**
0f30: 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 limits the size
0f40: 20 6f 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 of a row in a t
0f50: 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a able or index..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 *.** The hard li
0f70: 6d 69 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 mit is the abili
0f80: 74 79 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 ty of a 32-bit s
0f90: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
0fa0: 20 74 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 to count the si
0fb0: 7a 65 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 ze: 2^31-1 or 21
0fc0: 34 37 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 47483647..*/.#if
0fd0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f ndef SQLITE_MAX_
0fe0: 4c 45 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 LENGTH.# define
0ff0: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 SQLITE_MAX_LENGT
1000: 48 20 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e H 1000000000.#en
1010: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 dif../*.** This
1020: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e is the maximum n
1030: 75 6d 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 umber of.**.**
1040: 20 20 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 * Columns in a
1050: 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 table.** * C
1060: 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
1070: 65 78 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d ex.** * Colum
1080: 6e 73 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 ns in a view.**
1090: 20 20 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 * Terms in th
10a0: 65 20 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 e SET clause of
10b0: 61 6e 20 55 50 44 41 54 45 20 73 74 61 74 65 6d an UPDATE statem
10c0: 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d ent.** * Term
10d0: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
10e0: 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 set of a SELECT
10f0: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 statement.**
1100: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 * Terms in the G
1110: 52 4f 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 ROUP BY or ORDER
1120: 20 42 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 BY clauses of a
1130: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
1140: 74 2e 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 t..** * Terms
1150: 20 69 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 in the VALUES c
1160: 6c 61 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 lause of an INSE
1170: 52 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a RT statement.**.
1180: 2a 2a 20 54 68 65 20 68 61 72 64 20 75 70 70 65 ** The hard uppe
1190: 72 20 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 r limit here is
11a0: 33 32 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 32676. Most dat
11b0: 61 62 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c abase people wil
11c0: 6c 0a 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 l.** tell you th
11d0: 61 74 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 at in a well-nor
11e0: 6d 61 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 malized database
11f0: 2c 20 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 , you usually sh
1200: 6f 75 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 ould.** not have
1210: 20 6d 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a more than a doz
1220: 65 6e 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 en or so columns
1230: 20 69 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 in any table.
1240: 41 6e 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 And if.** that i
1250: 73 20 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 s the case, ther
1260: 65 20 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e e is no point in
1270: 20 68 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 having more tha
1280: 6e 20 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e n a few.** dozen
1290: 20 76 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f values in any o
12a0: 66 20 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 f the other situ
12b0: 61 74 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 ations described
12c0: 20 61 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 above..*/.#ifnd
12d0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f ef SQLITE_MAX_CO
12e0: 4c 55 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 LUMN.# define SQ
12f0: 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 LITE_MAX_COLUMN
1300: 32 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2000.#endif../*.
1310: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c ** The maximum l
1320: 65 6e 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c ength of a singl
1330: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1340: 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 in bytes..**.**
1350: 49 74 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 It used to be th
1360: 65 20 63 61 73 65 20 74 68 61 74 20 73 65 74 74 e case that sett
1370: 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 ing this value t
1380: 6f 20 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 o zero would.**
1390: 74 75 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f turn the limit o
13a0: 66 66 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 ff. That is no
13b0: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 longer true. It
13c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
13d0: 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 .** to turn this
13e0: 20 6c 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 limit off..*/.#
13f0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 ifndef SQLITE_MA
1400: 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 X_SQL_LENGTH.# d
1410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 efine SQLITE_MAX
1420: 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 _SQL_LENGTH 1000
1430: 30 30 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 000000.#endif../
1440: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d *.** The maximum
1450: 20 64 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 depth of an exp
1460: 72 65 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 ression tree. Th
1470: 69 73 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f is is limited to
1480: 20 0a 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 .** some extent
1490: 20 62 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 by SQLITE_MAX_S
14a0: 51 4c 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 QL_LENGTH. But s
14b0: 6f 6d 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 ometime you migh
14c0: 74 20 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c t .** want to pl
14d0: 61 63 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 ace more severe
14e0: 6c 69 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f limits on the co
14f0: 6d 70 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a mplexity of an .
1500: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a ** expression..*
1510: 2a 0a 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 *.** A value of
1520: 30 20 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 0 used to mean t
1530: 68 61 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 hat the limit wa
1540: 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a s not enforced..
1550: 2a 2a 20 42 75 74 20 74 68 61 74 20 69 73 20 6e ** But that is n
1560: 6f 20 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 o longer true.
1570: 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 The limit is now
1580: 20 73 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 strictly enforc
1590: 65 64 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d ed.** at all tim
15a0: 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 es..*/.#ifndef S
15b0: 51 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 QLITE_MAX_EXPR_D
15c0: 45 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 EPTH.# define SQ
15d0: 4c 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 LITE_MAX_EXPR_DE
15e0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a PTH 1000.#endif.
15f0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d ./*.** The maxim
1600: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 um number of ter
1610: 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 ms in a compound
1620: 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e SELECT statemen
1630: 74 2e 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 t..** The code g
1640: 65 6e 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d enerator for com
1650: 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 pound SELECT sta
1660: 74 65 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 tements does one
1670: 0a 2a 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 .** level of rec
1680: 75 72 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 ursion for each
1690: 74 65 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f term. A stack o
16a0: 76 65 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 verflow can resu
16b0: 6c 74 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d lt.** if the num
16c0: 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 ber of terms is
16d0: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 too large. In p
16e0: 72 61 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 ractice, most SQ
16f0: 4c 0a 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d L.** never has m
1700: 6f 72 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 ore than 3 or 4
1710: 74 65 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 terms. Use a va
1720: 6c 75 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 lue of 0 to disa
1730: 62 6c 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 ble.** any limit
1740: 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f on the number o
1750: 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d f terms in a com
1760: 70 6f 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f pount SELECT..*/
1770: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
1780: 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MAX_COMPOUND_SEL
1790: 45 43 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ECT.# define SQL
17a0: 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 ITE_MAX_COMPOUND
17b0: 5f 53 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 _SELECT 500.#end
17c0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 if../*.** The ma
17d0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
17e0: 6f 70 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 opcodes in a VDB
17f0: 45 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f E program..** No
1800: 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f t currently enfo
1810: 72 63 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 rced..*/.#ifndef
1820: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 SQLITE_MAX_VDBE
1830: 5f 4f 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c _OP.# define SQL
1840: 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 ITE_MAX_VDBE_OP
1850: 32 35 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 25000.#endif../*
1860: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 .** The maximum
1870: 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
1880: 6e 74 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 nts to an SQL fu
1890: 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 nction..*/.#ifnd
18a0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 ef SQLITE_MAX_FU
18b0: 4e 43 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 NCTION_ARG.# def
18c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 ine SQLITE_MAX_F
18d0: 55 4e 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a UNCTION_ARG 127.
18e0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 #endif../*.** Th
18f0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
1900: 20 6f 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 of in-memory pa
1910: 67 65 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 ges to use for t
1920: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
1930: 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f .** table and fo
1940: 72 20 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c r temporary tabl
1950: 65 73 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f es. The SQLITE_
1960: 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 DEFAULT_CACHE_SI
1970: 5a 45 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 ZE.*/.#ifndef SQ
1980: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 LITE_DEFAULT_CAC
1990: 48 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 HE_SIZE.# define
19a0: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f SQLITE_DEFAULT_
19b0: 43 41 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 CACHE_SIZE 2000
19c0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 .#endif.#ifndef
19d0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 SQLITE_DEFAULT_T
19e0: 45 4d 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 EMP_CACHE_SIZE.#
19f0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 define SQLITE_D
1a00: 45 46 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 EFAULT_TEMP_CACH
1a10: 45 5f 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 E_SIZE 500.#end
1a20: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 if../*.** The de
1a30: 66 61 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 fault number of
1a40: 66 72 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 frames to accumu
1a50: 6c 61 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 late in the log
1a60: 66 69 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 file before.** c
1a70: 68 65 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 heckpointing the
1a80: 20 64 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c database in WAL
1a90: 20 6d 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 mode..*/.#ifnde
1aa0: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 f SQLITE_DEFAULT
1ab0: 5f 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f _WAL_AUTOCHECKPO
1ac0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c INT.# define SQL
1ad0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f ITE_DEFAULT_WAL_
1ae0: 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 AUTOCHECKPOINT
1af0: 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 1000.#endif../*.
1b00: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e ** The maximum n
1b10: 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 umber of attache
1b20: 64 20 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 d databases. Th
1b30: 69 73 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 is must be betwe
1b40: 65 6e 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 en 0.** and 62.
1b50: 20 54 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 The upper bound
1b60: 20 6f 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 on 62 is becaus
1b70: 65 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 e a 64-bit integ
1b80: 65 72 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 er bitmap.** is
1b90: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
1ba0: 74 6f 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 to track attache
1bb0: 64 20 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a d databases..*/.
1bc0: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d #ifndef SQLITE_M
1bd0: 41 58 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 AX_ATTACHED.# de
1be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f fine SQLITE_MAX_
1bf0: 41 54 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 ATTACHED 10.#end
1c00: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d if.../*.** The m
1c10: 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 aximum value of
1c20: 61 20 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 a ?nnn wildcard
1c30: 74 68 61 74 20 74 68 65 20 70 61 72 73 65 72 20 that the parser
1c40: 77 69 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a will accept..*/.
1c50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d #ifndef SQLITE_M
1c60: 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 AX_VARIABLE_NUMB
1c70: 45 52 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 ER.# define SQLI
1c80: 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f TE_MAX_VARIABLE_
1c90: 4e 55 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 NUMBER 999.#endi
1ca0: 66 0a 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 f../* Maximum pa
1cb0: 67 65 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 ge size. The up
1cc0: 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 per bound on thi
1cd0: 73 20 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 s value is 65536
1ce0: 2e 20 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a . This a limit.
1cf0: 2a 2a 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 ** imposed by th
1d00: 65 20 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 e use of 16-bit
1d10: 6f 66 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 offsets within e
1d20: 61 63 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 ach page..**.**
1d30: 45 61 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 Earlier versions
1d40: 20 6f 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 of SQLite allow
1d50: 65 64 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 ed the user to c
1d60: 68 61 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 hange this value
1d70: 20 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 at.** compile t
1d80: 69 6d 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 ime. This is no
1d90: 6c 6f 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 longer permitted
1da0: 2c 20 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 , on the grounds
1db0: 20 74 68 61 74 20 69 74 20 63 72 65 61 74 65 73 that it creates
1dc0: 0a 2a 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 .** a library th
1dd0: 61 74 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c at is technicall
1de0: 79 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 y incompatible w
1df0: 69 74 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 ith an SQLite li
1e00: 62 72 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c brary .** compil
1e10: 65 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72 ed with a differ
1e20: 65 6e 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 ent limit. If a
1e30: 70 72 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e process operatin
1e40: 67 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 g on a database
1e50: 0a 2a 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d .** with a page-
1e60: 73 69 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 size of 65536 by
1e70: 74 65 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 tes crashes, the
1e80: 6e 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 n an instance of
1e90: 20 53 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 SQLite .** comp
1ea0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 64 65 iled with the de
1eb0: 66 61 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 fault page-size
1ec0: 6c 69 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 limit will not b
1ed0: 65 20 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 e able to rollba
1ee0: 63 6b 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 ck .** the abort
1ef0: 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 ed transaction.
1f00: 54 68 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 This could lead
1f10: 74 6f 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 to database corr
1f20: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 uption..*/.#ifde
1f30: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 f SQLITE_MAX_PAG
1f40: 45 5f 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 E_SIZE.# undef S
1f50: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 QLITE_MAX_PAGE_S
1f60: 49 5a 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 IZE.#endif.#defi
1f70: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 ne SQLITE_MAX_PA
1f80: 47 45 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a GE_SIZE 65536...
1f90: 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c /*.** The defaul
1fa0: 74 20 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 t size of a data
1fb0: 62 61 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 base page..*/.#i
1fc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 fndef SQLITE_DEF
1fd0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 AULT_PAGE_SIZE.#
1fe0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 define SQLITE_D
1ff0: 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 EFAULT_PAGE_SIZE
2000: 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 1024.#endif.#if
2010: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f SQLITE_DEFAULT_
2020: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 PAGE_SIZE>SQLITE
2030: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 _MAX_PAGE_SIZE.#
2040: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 undef SQLITE_DE
2050: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a FAULT_PAGE_SIZE.
2060: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
2070: 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a DEFAULT_PAGE_SIZ
2080: 45 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 E SQLITE_MAX_PAG
2090: 45 5f 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f E_SIZE.#endif../
20a0: 2a 0a 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c *.** Ordinarily,
20b0: 20 69 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 if no value is
20c0: 65 78 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 explicitly provi
20d0: 64 65 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 ded, SQLite crea
20e0: 74 65 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a tes databases.**
20f0: 20 77 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 with page size
2100: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 SQLITE_DEFAULT_P
2110: 41 47 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 AGE_SIZE. Howeve
2120: 72 2c 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 r, based on cert
2130: 61 69 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 ain.** device ch
2140: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 28 73 aracteristics (s
2150: 65 63 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 ector-size and a
2160: 74 6f 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 tomic write() su
2170: 70 70 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 pport),.** SQLit
2180: 65 20 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c e may choose a l
2190: 61 72 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 arger value. Thi
21a0: 73 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 s constant is th
21b0: 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a e maximum value.
21c0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 ** SQLite will c
21d0: 68 6f 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e hoose on its own
21e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
21f0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f ITE_MAX_DEFAULT_
2200: 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 PAGE_SIZE.# defi
2210: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 ne SQLITE_MAX_DE
2220: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 FAULT_PAGE_SIZE
2230: 38 31 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 8192.#endif.#if
2240: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 SQLITE_MAX_DEFAU
2250: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c LT_PAGE_SIZE>SQL
2260: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a ITE_MAX_PAGE_SIZ
2270: 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 E.# undef SQLITE
2280: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 _MAX_DEFAULT_PAG
2290: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 E_SIZE.# define
22a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 SQLITE_MAX_DEFAU
22b0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c LT_PAGE_SIZE SQL
22c0: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a ITE_MAX_PAGE_SIZ
22d0: 45 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a E.#endif.../*.**
22e0: 20 4d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 Maximum number
22f0: 6f 66 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 of pages in one
2300: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a database file..*
2310: 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 *.** This is rea
2320: 6c 6c 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 lly just the def
2330: 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 ault value for t
2340: 68 65 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e he max_page_coun
2350: 74 20 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 t pragma..** Thi
2360: 73 20 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c s value can be l
2370: 6f 77 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 owered (or raise
2380: 64 29 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 d) at run-time u
2390: 73 69 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a sing that the.**
23a0: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 max_page_count
23b0: 6d 61 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 macro..*/.#ifnde
23c0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 f SQLITE_MAX_PAG
23d0: 45 5f 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 E_COUNT.# define
23e0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
23f0: 5f 43 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 _COUNT 107374182
2400: 33 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 3.#endif../*.**
2410: 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 Maximum length (
2420: 69 6e 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 in bytes) of the
2430: 20 70 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 pattern in a LI
2440: 4b 45 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 KE or GLOB.** op
2450: 65 72 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 erator..*/.#ifnd
2460: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 ef SQLITE_MAX_LI
2470: 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
2480: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 H.# define SQLIT
2490: 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 E_MAX_LIKE_PATTE
24a0: 52 4e 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a RN_LENGTH 50000.
24b0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 #endif../*.** Ma
24c0: 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 ximum depth of r
24d0: 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 ecursion for tri
24e0: 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 ggers..**.** A v
24f0: 61 6c 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 alue of 1 means
2500: 74 68 61 74 20 61 20 74 72 69 67 67 65 72 20 70 that a trigger p
2510: 72 6f 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 rogram will not
2520: 62 65 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c be able to itsel
2530: 66 0a 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 f.** fire any tr
2540: 69 67 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 iggers. A value
2550: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 of 0 means that
2560: 6e 6f 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 no trigger progr
2570: 61 6d 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d ams at all .** m
2580: 61 79 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a ay be executed..
2590: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
25a0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 E_MAX_TRIGGER_DE
25b0: 50 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c PTH.# define SQL
25c0: 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f ITE_MAX_TRIGGER_
25d0: 44 45 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 DEPTH 1000.#endi
25e0: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a f../************
25f0: 2a 2a 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 ** End of sqlite
2600: 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a Limit.h ********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2630: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
2640: 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 ** Continuing wh
2650: 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 ere we left off
2660: 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a in sqliteInt.h *
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2680: 2a 2f 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e */../* Disable n
2690: 75 69 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 uisance warnings
26a0: 20 6f 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 on Borland comp
26b0: 69 6c 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 ilers */.#if def
26c0: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
26d0: 5f 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 _).#pragma warn
26e0: 2d 72 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 -rch /* unreacha
26f0: 62 6c 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 ble code */.#pra
2700: 67 6d 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a gma warn -ccc /*
2710: 20 43 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c Condition is al
2720: 77 61 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c ways true or fal
2730: 73 65 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 se */.#pragma wa
2740: 72 6e 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 rn -aus /* Assig
2750: 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 ned value is nev
2760: 65 72 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 er used */.#prag
2770: 6d 61 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 ma warn -csu /*
2780: 43 6f 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 Comparing signed
2790: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f and unsigned */
27a0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 .#pragma warn -s
27b0: 70 61 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 pa /* Suspicious
27c0: 20 70 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 pointer arithme
27d0: 74 69 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f tic */.#endif../
27e0: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 * Needed for var
27f0: 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 ious definitions
2800: 2e 2e 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f ... */.#ifndef _
2810: 47 4e 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 GNU_SOURCE.# def
2820: 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a ine _GNU_SOURCE.
2830: 23 65 6e 64 69 66 0a 0a 23 69 66 20 64 65 66 69 #endif..#if defi
2840: 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 ned(__OpenBSD__)
2850: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 42 53 && !defined(_BS
2860: 44 5f 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 D_SOURCE).# defi
2870: 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 ne _BSD_SOURCE.#
2880: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 endif../*.** Inc
2890: 6c 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 lude standard he
28a0: 61 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 ader files as ne
28b0: 63 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 cessary.*/.#ifde
28c0: 66 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a f HAVE_STDINT_H.
28d0: 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 #include <stdint
28e0: 2e 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 .h>.#endif.#ifde
28f0: 66 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f f HAVE_INTTYPES_
2900: 48 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 H.#include <intt
2910: 79 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a ypes.h>.#endif..
2920: 2f 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 /*.** The follow
2930: 69 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 ing macros are u
2940: 73 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e sed to cast poin
2950: 74 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 ters to integers
2960: 20 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 and.** integers
2970: 20 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 to pointers. T
2980: 68 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 he way you do th
2990: 69 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f is varies from o
29a0: 6e 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 ne compiler.** t
29b0: 6f 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 o the next, so w
29c0: 65 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 e have developed
29d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 the following s
29e0: 65 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d et of #if statem
29f0: 65 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 ents.** to gener
2a00: 61 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 ate appropriate
2a10: 6d 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 macros for a wid
2a20: 65 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 e range of compi
2a30: 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lers..**.** The
2a40: 63 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 correct "ANSI" w
2a50: 61 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 ay to do this is
2a60: 20 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 to use the intp
2a70: 74 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 tr_t type. .** U
2a80: 6e 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 nfortunately, th
2a90: 61 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f at typedef is no
2aa0: 74 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 t available on a
2ab0: 6c 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 ll compilers, or
2ac0: 0a 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 .** if it is ava
2ad0: 69 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 ilable, it requi
2ae0: 72 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 res an #include
2af0: 6f 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 of specific head
2b00: 65 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 ers.** that vary
2b10: 20 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e from one machin
2b20: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
2b30: 2a 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 *.** Ticket #386
2b40: 30 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 0: The llvm-gcc
2b50: 2d 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 -4.2 compiler fr
2b60: 6f 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 om Apple chokes
2b70: 6f 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 on.** the ((void
2b80: 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d *)&((char*)0)[X]
2b90: 29 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 ) construct. Bu
2ba0: 74 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e t MSVC chokes on
2bb0: 20 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a ((void*)(X))..*
2bc0: 2a 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 * So we have to
2bd0: 64 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f define the macro
2be0: 73 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 s in different w
2bf0: 61 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ays depending on
2c00: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 the.** compiler
2c10: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 ..*/.#if defined
2c20: 28 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f (__PTRDIFF_TYPE_
2c30: 5f 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 _) /* This case
2c40: 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 should work for
2c50: 20 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 GCC */.# define
2c60: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 SQLITE_INT_TO_P
2c70: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 TR(X) ((void*)(
2c80: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f __PTRDIFF_TYPE__
2c90: 29 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 )(X)).# define S
2ca0: 51 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 QLITE_PTR_TO_INT
2cb0: 28 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 (X) ((int)(__PT
2cc0: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 RDIFF_TYPE__)(X)
2cd0: 29 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 ).#elif !defined
2ce0: 28 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 (__GNUC__)
2cf0: 20 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f /* Works for co
2d00: 6d 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 mpilers other th
2d10: 61 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 an LLVM */.# def
2d20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 ine SQLITE_INT_T
2d30: 4f 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 O_PTR(X) ((void
2d40: 2a 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d *)&((char*)0)[X]
2d50: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 ).# define SQLIT
2d60: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 E_PTR_TO_INT(X)
2d70: 20 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 ((int)(((char*)
2d80: 58 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 X)-(char*)0)).#e
2d90: 6c 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 lif defined(HAVE
2da0: 5f 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 _STDINT_H) /*
2db0: 55 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 Use this case if
2dc0: 20 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 we have ANSI he
2dd0: 61 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e aders */.# defin
2de0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f e SQLITE_INT_TO_
2df0: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 PTR(X) ((void*)
2e00: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 (intptr_t)(X)).#
2e10: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 define SQLITE_P
2e20: 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 TR_TO_INT(X) ((
2e30: 69 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 int)(intptr_t)(X
2e40: 29 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 )).#else
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e60: 20 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 /* Generates a
2e70: 20 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 warning - but i
2e80: 74 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a t always works *
2e90: 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 /.# define SQLIT
2ea0: 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 E_INT_TO_PTR(X)
2eb0: 20 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 ((void*)(X)).#
2ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 define SQLITE_PT
2ed0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 R_TO_INT(X) ((i
2ee0: 6e 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a nt)(X)).#endif..
2ef0: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 /*.** The SQLITE
2f00: 5f 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 _THREADSAFE macr
2f10: 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 o must be define
2f20: 64 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e d as 0, 1, or 2.
2f30: 0a 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 .** 0 means mute
2f40: 78 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e xes are permanen
2f50: 74 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 tly disable and
2f60: 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e the library is n
2f70: 65 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 ever.** threadsa
2f80: 66 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 fe. 1 means the
2f90: 20 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 library is seri
2fa0: 61 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 alized which is
2fb0: 74 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c the highest.** l
2fc0: 65 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 evel of threadsa
2fd0: 66 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 fety. 2 means t
2fe0: 68 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c he libary is mul
2ff0: 74 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c tithreaded - mul
3000: 74 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 tiple.** threads
3010: 20 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 can use SQLite
3020: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 as long as no tw
3030: 6f 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f o threads try to
3040: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
3050: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3060: 74 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 tion at the same
3070: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 time..**.** Old
3080: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 er versions of S
3090: 51 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 QLite used an op
30a0: 74 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 tional THREADSAF
30b0: 45 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 E macro..** We s
30c0: 75 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 upport that for
30d0: 6c 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 legacy..*/.#if !
30e0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 defined(SQLITE_T
30f0: 48 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 HREADSAFE).#if d
3100: 65 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 efined(THREADSAF
3110: 45 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 E).# define SQLI
3120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 TE_THREADSAFE TH
3130: 52 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 READSAFE.#else.#
3140: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
3150: 48 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 HREADSAFE 1 /* I
3160: 4d 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 MP: R-07272-2230
3170: 39 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 9 */.#endif.#end
3180: 69 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 if../*.** Powers
3190: 61 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 afe overwrite is
31a0: 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 on by default.
31b0: 20 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e But can be turn
31c0: 65 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 ed off using.**
31d0: 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 the -DSQLITE_POW
31e0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
31f0: 3d 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 =0 command-line
3200: 6f 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 option..*/.#ifnd
3210: 65 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 ef SQLITE_POWERS
3220: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 AFE_OVERWRITE.#
3230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f define SQLITE_PO
3240: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
3250: 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a E 1.#endif../*.*
3260: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 * The SQLITE_DEF
3270: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d AULT_MEMSTATUS m
3280: 61 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 acro must be def
3290: 69 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 ined as either 0
32a0: 20 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 or 1..** It det
32b0: 65 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 ermines whether
32c0: 6f 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 or not the featu
32d0: 72 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a res related to .
32e0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
32f0: 5f 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 _MEMSTATUS are a
3300: 76 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 vailable by defa
3310: 75 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 ult or not. This
3320: 20 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 value can.** be
3330: 20 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 overridden at r
3340: 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 untime using the
3350: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
3360: 29 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 ) API..*/.#if !d
3370: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 efined(SQLITE_DE
3380: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 FAULT_MEMSTATUS)
3390: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
33a0: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 _DEFAULT_MEMSTAT
33b0: 55 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a US 1.#endif../*.
33c0: 2a 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f ** Exactly one o
33d0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
33e0: 6d 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 macros must be d
33f0: 65 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 efined in order
3400: 74 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 to.** specify wh
3410: 69 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ich memory alloc
3420: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 ation subsystem
3430: 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 to use..**.**
3440: 20 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f SQLITE_SYSTEM_
3450: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 MALLOC
3460: 2f 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 // Use normal sy
3470: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a stem malloc().**
3480: 20 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 SQLITE_WIN3
3490: 32 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 2_MALLOC
34a0: 20 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 // Use Win32
34b0: 6e 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a native heap API.
34c0: 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 ** SQLITE_ZE
34d0: 52 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 RO_MALLOC
34e0: 20 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 // Use a st
34f0: 75 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ub allocator tha
3500: 74 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a t always fails.*
3510: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d * SQLITE_MEM
3520: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 DEBUG
3530: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 // Debugging
3540: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 version of syst
3550: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a em malloc().**.*
3560: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 * On Windows, if
3570: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 the SQLITE_WIN3
3580: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 2_MALLOC_VALIDAT
3590: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e E macro is defin
35a0: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 ed and the.** as
35b0: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 sert() macro is
35c0: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 enabled, each ca
35d0: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 ll into the Win3
35e0: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 2 native heap su
35f0: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 bsystem.** will
3600: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 cause HeapValida
3610: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e te to be called.
3620: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 If heap valida
3630: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c tion should fail
3640: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f , an.** assertio
3650: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 n will be trigge
3660: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 red..**.** (Hist
3670: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 orical note: Th
3680: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 ere used to be s
3690: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 everal other opt
36a0: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a ions, but we've.
36b0: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e ** pared it down
36c0: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 to just these t
36d0: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 hree.).**.** If
36e0: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 none of the abov
36f0: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 e are defined, t
3700: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 hen set SQLITE_S
3710: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a YSTEM_MALLOC as.
3720: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a ** the default..
3730: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 */.#if defined(S
3740: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c QLITE_SYSTEM_MAL
3750: 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e LOC) \. + defin
3760: 65 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f ed(SQLITE_WIN32_
3770: 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 MALLOC) \. + de
3780: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 fined(SQLITE_ZER
3790: 4f 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 O_MALLOC) \. +
37a0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d defined(SQLITE_M
37b0: 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 EMDEBUG)>1.# err
37c0: 6f 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 or "Two or more
37d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
37e0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f compile-time co
37f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
3800: 6f 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 ons\. are define
3810: 64 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e d but at most on
3820: 65 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 e is allowed:\.
3830: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 SQLITE_SYSTEM_MA
3840: 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e LLOC, SQLITE_WIN
3850: 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 32_MALLOC, SQLIT
3860: 45 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 E_MEMDEBUG,\. SQ
3870: 4c 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 LITE_ZERO_MALLOC
3880: 22 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 ".#endif.#if def
3890: 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 ined(SQLITE_SYST
38a0: 45 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b EM_MALLOC) \. +
38b0: 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f defined(SQLITE_
38c0: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a WIN32_MALLOC) \.
38d0: 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 + defined(SQLI
38e0: 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 TE_ZERO_MALLOC)
38f0: 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 \. + defined(SQ
3900: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d LITE_MEMDEBUG)==
3910: 30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 0.# define SQLIT
3920: 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 E_SYSTEM_MALLOC
3930: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 1.#endif../*.**
3940: 49 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 If SQLITE_MALLOC
3950: 5f 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e _SOFT_LIMIT is n
3960: 6f 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 ot zero, then tr
3970: 79 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a y to keep the.**
3980: 20 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 sizes of memory
3990: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c allocations bel
39a0: 6f 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 ow this value wh
39b0: 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f ere possible..*/
39c0: 0a 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 .#if !defined(SQ
39d0: 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 LITE_MALLOC_SOFT
39e0: 5f 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 _LIMIT).# define
39f0: 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 SQLITE_MALLOC_S
3a00: 4f 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 OFT_LIMIT 1024.#
3a10: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 endif../*.** We
3a20: 6e 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f need to define _
3a30: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 XOPEN_SOURCE as
3a40: 66 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 follows in order
3a50: 20 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 to enable.** re
3a60: 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 cursive mutexes
3a70: 6f 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 on most Unix sys
3a80: 74 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f tems. But Mac O
3a90: 53 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 S X is different
3aa0: 2e 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f ..** The _XOPEN_
3ab0: 53 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 SOURCE define ca
3ac0: 75 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f uses problems fo
3ad0: 72 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 r Mac OS X we ar
3ae0: 65 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 e told,.** so it
3af0: 20 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 is omitted ther
3b00: 65 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 e. See ticket #
3b10: 32 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 2673..**.** Late
3b20: 72 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 r we learn that
3b30: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 _XOPEN_SOURCE is
3b40: 20 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 poorly or incor
3b50: 72 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d rectly.** implem
3b60: 65 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 ented on some sy
3b70: 73 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 stems. So we av
3b80: 6f 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 oid defining it
3b90: 61 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 at all.** if it
3ba0: 69 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e is already defin
3bb0: 65 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 ed or if it is u
3bc0: 6e 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 nneeded because
3bd0: 77 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f we are.** not do
3be0: 69 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 ing a threadsafe
3bf0: 20 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 build. Ticket
3c00: 23 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 #2681..**.** See
3c10: 20 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 also ticket #27
3c20: 34 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 41..*/.#if !defi
3c30: 6e 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 ned(_XOPEN_SOURC
3c40: 45 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f E) && !defined(_
3c50: 5f 44 41 52 57 49 4e 5f 5f 29 20 5c 0a 20 26 26 _DARWIN__) \. &&
3c60: 20 21 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c !defined(__APPL
3c70: 45 5f 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 E__) && SQLITE_T
3c80: 48 52 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 HREADSAFE.# def
3c90: 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 ine _XOPEN_SOURC
3ca0: 45 20 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 E 500 /* Needed
3cb0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 to enable pthre
3cc0: 61 64 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 ad recursive mut
3cd0: 65 78 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a exes */.#endif..
3ce0: 2f 2a 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 /*.** The TCL he
3cf0: 61 64 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e aders are only n
3d00: 65 65 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 eeded when compi
3d10: 6c 69 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e ling the TCL bin
3d20: 64 69 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 dings..*/.#if de
3d30: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c fined(SQLITE_TCL
3d40: 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c ) || defined(TCL
3d50: 53 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 SH).# include <t
3d60: 63 6c 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a cl.h>.#endif../*
3d70: 0a 2a 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53 .** NDEBUG and S
3d80: 51 4c 49 54 45 5f 44 45 42 55 47 20 61 72 65 20 QLITE_DEBUG are
3d90: 6f 70 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73 opposites. It s
3da0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20 hould always be
3db0: 74 72 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66 true that.** def
3dc0: 69 6e 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64 ined(NDEBUG)==!d
3dd0: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 efined(SQLITE_DE
3de0: 42 55 47 29 2e 20 20 49 66 20 74 68 69 73 20 69 BUG). If this i
3df0: 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
3e00: 74 72 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 true,.** make it
3e10: 20 74 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e true by definin
3e20: 67 20 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20 g or undefining
3e30: 4e 44 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 NDEBUG..**.** Se
3e40: 74 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b tting NDEBUG mak
3e50: 65 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c es the code smal
3e60: 6c 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 ler and run fast
3e70: 65 72 20 62 79 20 64 69 73 61 62 6c 69 6e 67 20 er by disabling
3e80: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 73 the.** number as
3e90: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 sert() statement
3ea0: 73 20 69 6e 20 74 68 65 20 63 6f 64 65 2e 20 20 s in the code.
3eb0: 53 6f 20 77 65 20 77 61 6e 74 20 74 68 65 20 64 So we want the d
3ec0: 65 66 61 75 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a efault action.**
3ed0: 20 74 6f 20 62 65 20 66 6f 72 20 4e 44 45 42 55 to be for NDEBU
3ee0: 47 20 74 6f 20 62 65 20 73 65 74 20 61 6e 64 20 G to be set and
3ef0: 4e 44 45 42 55 47 20 74 6f 20 62 65 20 75 6e 64 NDEBUG to be und
3f00: 65 66 69 6e 65 64 20 6f 6e 6c 79 20 69 66 20 53 efined only if S
3f10: 51 4c 49 54 45 5f 44 45 42 55 47 0a 2a 2a 20 69 QLITE_DEBUG.** i
3f20: 73 20 73 65 74 2e 20 20 54 68 75 73 20 4e 44 45 s set. Thus NDE
3f30: 42 55 47 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f BUG becomes an o
3f40: 70 74 2d 69 6e 20 72 61 74 68 65 72 20 74 68 61 pt-in rather tha
3f50: 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 n an opt-out.**
3f60: 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 feature..*/.#if
3f70: 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 !defined(NDEBUG)
3f80: 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c && !defined(SQL
3f90: 49 54 45 5f 44 45 42 55 47 29 20 0a 23 20 64 65 ITE_DEBUG) .# de
3fa0: 66 69 6e 65 20 4e 44 45 42 55 47 20 31 0a 23 65 fine NDEBUG 1.#e
3fb0: 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64 ndif.#if defined
3fc0: 28 4e 44 45 42 55 47 29 20 26 26 20 64 65 66 69 (NDEBUG) && defi
3fd0: 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 ned(SQLITE_DEBUG
3fe0: 29 0a 23 20 75 6e 64 65 66 20 4e 44 45 42 55 47 ).# undef NDEBUG
3ff0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 .#endif../*.** T
4000: 68 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 he testcase() ma
4010: 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 cro is used to a
4020: 69 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 id in coverage t
4030: 65 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a esting. When .*
4040: 2a 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 * doing coverage
4050: 20 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f testing, the co
4060: 6e 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 ndition inside t
4070: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
4080: 2a 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 * testcase() mus
4090: 74 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 t be evaluated b
40a0: 6f 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c oth true and fal
40b0: 73 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a se in order to.*
40c0: 2a 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 * get full branc
40d0: 68 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 h coverage. The
40e0: 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 testcase() macr
40f0: 6f 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a o is inserted.**
4100: 20 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 to help ensure
4110: 61 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f adequate test co
4120: 76 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 verage in places
4130: 20 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a where simple.**
4140: 20 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 condition/decis
4150: 69 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 ion coverage is
4160: 69 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 inadequate. For
4170: 20 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 example, testca
4180: 73 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 se().** can be u
4190: 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 sed to make sure
41a0: 20 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 boundary values
41b0: 20 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f are tested. Fo
41c0: 72 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 r.** bitmask tes
41d0: 74 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 ts, testcase() c
41e0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 an be used to ma
41f0: 6b 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74 ke sure each bit
4200: 0a 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 .** is significa
4210: 6e 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c nt and used at l
4220: 65 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 east once. On s
4230: 77 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 witch statements
4240: 0a 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 .** where multip
4250: 6c 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 le cases go to t
4260: 68 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 he same block of
4270: 20 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 code, testcase(
4280: 29 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 ).** can insure
4290: 74 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 that all cases a
42a0: 72 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a re evaluated..**
42b0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
42c0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a E_COVERAGE_TEST.
42d0: 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 SQLITE_PRIVATE
42e0: 20 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 void sqlite3Cov
42f0: 65 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 erage(int);.# de
4300: 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 fine testcase(X)
4310: 20 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 if( X ){ sqlit
4320: 65 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e e3Coverage(__LIN
4330: 45 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 E__); }.#else.#
4340: 64 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 define testcase(
4350: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a X).#endif../*.**
4360: 20 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 The TESTONLY ma
4370: 63 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 cro is used to e
4380: 6e 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 nclose variable
4390: 64 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a declarations or.
43a0: 2a 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 ** other bits of
43b0: 20 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e code that are n
43c0: 65 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 eeded to support
43d0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a the arguments.*
43e0: 2a 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 * within testcas
43f0: 65 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 e() and assert()
4400: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 macros..*/.#if
4410: 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 !defined(NDEBUG)
4420: 20 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 || defined(SQLI
4430: 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 TE_COVERAGE_TEST
4440: 29 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f ).# define TESTO
4450: 4e 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a NLY(X) X.#else.
4460: 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c # define TESTONL
4470: 59 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a Y(X).#endif../*.
4480: 2a 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 ** Sometimes we
4490: 6e 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f need a small amo
44a0: 75 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 unt of code such
44b0: 20 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 as a variable i
44c0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a nitialization.**
44d0: 20 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 to setup for a
44e0: 6c 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73 later assert() s
44f0: 74 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f tatement. We do
4500: 20 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 not want this c
4510: 6f 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 ode to.** appear
4520: 20 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 when assert() i
4530: 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 s disabled. The
4540: 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f following macro
4550: 20 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a is therefore.**
4560: 20 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e used to contain
4570: 20 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 that setup code
4580: 2e 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72 . The "VVA" acr
4590: 6f 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a onym stands for.
45a0: 2a 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e ** "Verification
45b0: 2c 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e , Validation, an
45c0: 64 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 d Accreditation"
45d0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
45e0: 73 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 s, the.** code w
45f0: 69 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 ithin VVA_ONLY()
4600: 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 will only run d
4610: 75 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 uring verificati
4620: 6f 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f on processes..*/
4630: 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a .#ifndef NDEBUG.
4640: 23 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c # define VVA_ONL
4650: 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 Y(X) X.#else.#
4660: 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 define VVA_ONLY(
4670: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a X).#endif../*.**
4680: 20 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 The ALWAYS and
4690: 4e 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 NEVER macros sur
46a0: 72 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 round boolean ex
46b0: 70 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 pressions which
46c0: 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 .** are intended
46d0: 20 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 to always be tr
46e0: 75 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 ue or false, res
46f0: 70 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 pectively. Such
4700: 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 .** expressions
4710: 63 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 could be omitted
4720: 20 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 from the code c
4730: 6f 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 ompletely. But
4740: 74 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c they.** are incl
4750: 75 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 uded in a few ca
4760: 73 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ses in order to
4770: 65 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 enhance the resi
4780: 6c 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c lience.** of SQL
4790: 69 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 ite to unexpecte
47a0: 64 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 d behavior - to
47b0: 6d 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 make the code "s
47c0: 65 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 elf-healing".**
47d0: 6f 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 or "ductile" rat
47e0: 68 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 her than being "
47f0: 62 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 brittle" and cra
4800: 73 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 shing at the fir
4810: 73 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e st.** hint of un
4820: 70 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 planned behavior
4830: 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ..**.** In other
4840: 20 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 words, ALWAYS a
4850: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 nd NEVER are add
4860: 65 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 ed for defensive
4870: 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 code..**.** Whe
4880: 6e 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 n doing coverage
4890: 20 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 testing ALWAYS
48a0: 61 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 and NEVER are ha
48b0: 72 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 rd-coded to.** b
48c0: 65 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 e true and false
48d0: 20 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 so that the unr
48e0: 65 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 eachable code th
48f0: 65 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a en specify will.
4900: 2a 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 ** not be counte
4910: 64 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f d as untested co
4920: 64 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e de..*/.#if defin
4930: 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 ed(SQLITE_COVERA
4940: 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e GE_TEST).# defin
4950: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 e ALWAYS(X)
4960: 20 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 (1).# define NE
4970: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29 VER(X) (0)
4980: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 .#elif !defined(
4990: 4e 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 NDEBUG).# define
49a0: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 ALWAYS(X)
49b0: 28 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 ((X)?1:(assert(0
49c0: 29 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e ),0)).# define N
49d0: 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28 EVER(X) ((
49e0: 58 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 X)?(assert(0),1)
49f0: 3a 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 :0).#else.# defi
4a00: 6e 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 ne ALWAYS(X)
4a10: 20 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e (X).# define N
4a20: 45 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58 EVER(X) (X
4a30: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ).#endif../*.**
4a40: 52 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e Return true (non
4a50: 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e -zero) if the in
4a60: 70 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 put is a integer
4a70: 20 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 that is too lar
4a80: 67 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 ge.** to fit in
4a90: 33 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 32-bits. This m
4aa0: 61 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 acro is used ins
4ab0: 69 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 ide of various t
4ac0: 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 estcase().** mac
4ad0: 72 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 ros to verify th
4ae0: 61 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65 at we have teste
4af0: 64 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 d SQLite for lar
4b00: 67 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e ge-file support.
4b10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 .*/.#define IS_B
4b20: 49 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 IG_INT(X) (((X)
4b30: 26 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66 &~(i64)0xfffffff
4b40: 66 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 f)!=0)../*.** Th
4b50: 65 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 e macro unlikely
4b60: 28 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 () is a hint tha
4b70: 74 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f t surrounds a bo
4b80: 6f 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 olean.** express
4b90: 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 ion that is usua
4ba0: 6c 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 lly false. Macr
4bb0: 6f 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f o likely() surro
4bc0: 75 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 unds.** a boolea
4bd0: 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 n expression tha
4be0: 74 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 t is usually tru
4bf0: 65 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 e. GCC is able
4c00: 74 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 to.** use these
4c10: 68 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 hints to generat
4c20: 65 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 e better code, s
4c30: 6f 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 ometimes..*/.#if
4c40: 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f defined(__GNUC_
4c50: 5f 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 _) && 0.# define
4c60: 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f likely(X) __
4c70: 62 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 builtin_expect((
4c80: 58 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 X),1).# define u
4c90: 6e 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 nlikely(X) __bu
4ca0: 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 iltin_expect((X)
4cb0: 2c 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 ,0).#else.# defi
4cc0: 6e 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 ne likely(X)
4cd0: 21 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 !!(X).# define u
4ce0: 6e 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 nlikely(X) !!(X
4cf0: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a ).#endif../*****
4d00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 ********* Includ
4d10: 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 e sqlite3.h in t
4d20: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c he middle of sql
4d30: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a iteInt.h *******
4d40: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a ********/./*****
4d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
4d60: 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a file sqlite3.h *
4d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d90: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
4da0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 2001 September 1
4db0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 5.**.** The auth
4dc0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 or disclaims cop
4dd0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 yright to this s
4de0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 ource code. In
4df0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 place of.** a le
4e00: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 gal notice, here
4e10: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a is a blessing:.
4e20: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 **.** May you
4e30: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 do good and not
4e40: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 evil..** May
4e50: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 you find forgiv
4e60: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 eness for yourse
4e70: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f lf and forgive o
4e80: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 thers..** May
4e90: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c you share freel
4ea0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 y, never taking
4eb0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 more than you gi
4ec0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a ve..**.*********
4ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4f10: 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 .** This header
4f20: 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 file defines the
4f30: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
4f40: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
4f50: 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 ry.** presents t
4f60: 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d o client program
4f70: 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 s. If a C-funct
4f80: 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 ion, structure,
4f90: 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 datatype,.** or
4fa0: 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 constant definit
4fb0: 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 ion does not app
4fc0: 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 ear in this file
4fd0: 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 , then it is.**
4fe0: 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 not a published
4ff0: 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 API of SQLite, i
5000: 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
5010: 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e nge without.** n
5020: 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c otice, and shoul
5030: 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e d not be referen
5040: 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 ced by programs
5050: 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e that use SQLite.
5060: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 .**.** Some of t
5070: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 he definitions t
5080: 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 hat are in this
5090: 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 file are marked
50a0: 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e as.** "experimen
50b0: 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e tal". Experimen
50c0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 tal interfaces a
50d0: 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a re normally new.
50e0: 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 ** features rece
50f0: 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 ntly added to SQ
5100: 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 Lite. We do not
5110: 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e anticipate chan
5120: 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 ges.** to experi
5130: 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 mental interface
5140: 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 s but reserve th
5150: 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 e right to make
5160: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a minor changes.**
5170: 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 if experience f
5180: 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 rom use "in the
5190: 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 wild" suggest su
51a0: 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 ch changes are p
51b0: 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 rudent..**.** Th
51c0: 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e e official C-lan
51d0: 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 guage API docume
51e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 ntation for SQLi
51f0: 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a te is derived.**
5200: 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 from comments i
5210: 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 n this file. Th
5220: 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 is file is the a
5230: 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 uthoritative sou
5240: 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 rce.** on how SQ
5250: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
5260: 61 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f are suppose to o
5270: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
5280: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
5290: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
52a0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
52b0: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
52c0: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
52d0: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
52e0: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
52f0: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
5300: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
5310: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
5320: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
5330: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
5340: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
5350: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
5360: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
5370: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f ndef _SQLITE3_H_
5380: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 .#define _SQLITE
5390: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 3_H_.#include <s
53a0: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 tdarg.h> /*
53b0: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 Needed for the d
53c0: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f efinition of va_
53d0: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d list */../*.** M
53e0: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 ake sure we can
53f0: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 call this stuff
5400: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 from C++..*/.#if
5410: 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 0.extern "C" {.
5420: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 #endif.../*.** A
5430: 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 dd the ability t
5440: 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 o override 'exte
5450: 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 rn'.*/.#ifndef S
5460: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 QLITE_EXTERN.# d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 efine SQLITE_EXT
5480: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 ERN extern.#endi
5490: 66 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 f..#ifndef SQLIT
54a0: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 E_API.# define S
54b0: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 QLITE_API.#endif
54c0: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e .../*.** These n
54d0: 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 o-op macros are
54e0: 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 used in front of
54f0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d interfaces to m
5500: 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 ark those.** int
5510: 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 erfaces as eithe
5520: 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 r deprecated or
5530: 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e experimental. N
5540: 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a ew applications.
5550: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 ** should not us
5560: 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 e deprecated int
5570: 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 erfaces - they a
5580: 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 re support for b
5590: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
55a0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 atibility only.
55b0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 Application wri
55c0: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 ters should be a
55d0: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 ware that.** exp
55e0: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
55f0: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 aces are subject
5600: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f to change in po
5610: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a int releases..**
5620: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 .** These macros
5630: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 used to resolve
5640: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 to various kind
5650: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 s of compiler ma
5660: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c gic that.** woul
5670: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 d generate warni
5680: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e ng messages when
5690: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e they were used.
56a0: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f But that.** co
56b0: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 mpiler magic end
56c0: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 ed up generating
56d0: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f such a flurry o
56e0: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a f bug reports.**
56f0: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 that we have ta
5700: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 ken it all out a
5710: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 nd gone back to
5720: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 using simple.**
5730: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a noop macros..*/.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
5750: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e EPRECATED.#defin
5760: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d e SQLITE_EXPERIM
5770: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 ENTAL../*.** Ens
5780: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c ure these symbol
5790: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e s were not defin
57a0: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 ed by some previ
57b0: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e ous header file.
57c0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
57d0: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 E_VERSION.# unde
57e0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
57f0: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
5800: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
5810: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c MBER.# undef SQL
5820: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
5830: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a ER.#endif../*.**
5840: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
5850: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 le-Time Library
5860: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
5870: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c **.** ^(The [SQL
5880: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 ITE_VERSION] C p
5890: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
58a0: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 o in the sqlite3
58b0: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 .h header.** eva
58c0: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 luates to a stri
58d0: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 ng literal that
58e0: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 is the SQLite ve
58f0: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 rsion in the.**
5900: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 format "X.Y.Z" w
5910: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 here X is the ma
5920: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 jor version numb
5930: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 er (always 3 for
5940: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 .** SQLite3) and
5950: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
5960: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
5970: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 nd Z is the rele
5980: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a ase number.)^.**
5990: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 ^(The [SQLITE_V
59a0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 ERSION_NUMBER] C
59b0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
59c0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
59d0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 an integer.** wi
59e0: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a th the value (X*
59f0: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 1000000 + Y*1000
5a00: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 + Z) where X, Y
5a10: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 , and Z are the
5a20: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 same.** numbers
5a30: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f used in [SQLITE_
5a40: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 VERSION].)^.** T
5a50: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f he SQLITE_VERSIO
5a60: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 N_NUMBER for any
5a70: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f given release o
5a80: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c f SQLite will al
5a90: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 so.** be larger
5aa0: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 than the release
5ab0: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 from which it i
5ac0: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 s derived. Eith
5ad0: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 er Y will.** be
5ae0: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e held constant an
5af0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 d Z will be incr
5b00: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 emented or else
5b10: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d Y will be increm
5b20: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 ented.** and Z w
5b30: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 ill be reset to
5b40: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 zero..**.** Sinc
5b50: 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 e version 3.6.18
5b60: 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 , SQLite source
5b70: 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 code has been st
5b80: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c ored in the.** <
5b90: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 a href="http://w
5ba0: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 ww.fossil-scm.or
5bb0: 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 g/">Fossil confi
5bc0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
5bd0: 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 ent.** system</a
5be0: 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f >. ^The SQLITE_
5bf0: 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 SOURCE_ID macro
5c00: 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 evaluates to.**
5c10: 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 a string which i
5c20: 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 dentifies a part
5c30: 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 icular check-in
5c40: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 of SQLite.** wit
5c50: 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 hin its configur
5c60: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 ation management
5c70: 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 system. ^The S
5c80: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a QLITE_SOURCE_ID.
5c90: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
5ca0: 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 ns the date and
5cb0: 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 time of the chec
5cc0: 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 k-in (UTC) and a
5cd0: 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f n SHA1.** hash o
5ce0: 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 f the entire sou
5cf0: 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 rce tree..**.**
5d00: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
5d10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d e3_libversion()]
5d20: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 ,.** [sqlite3_li
5d30: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
5d40: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 )], [sqlite3_sou
5d50: 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 rceid()],.** [sq
5d60: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 lite_version()]
5d70: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 and [sqlite_sour
5d80: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 ce_id()]..*/.#de
5d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 fine SQLITE_VERS
5da0: 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e ION "3.7.
5db0: 31 36 2e 31 22 0a 23 64 65 66 69 6e 65 20 53 51 16.1".#define SQ
5dc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
5dd0: 42 45 52 20 33 30 30 37 30 31 36 0a 23 64 65 66 BER 3007016.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 ine SQLITE_SOURC
5df0: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d E_ID "2013-
5e00: 30 33 2d 32 37 20 32 30 3a 34 31 3a 31 35 20 32 03-27 20:41:15 2
5e10: 37 34 64 32 61 32 32 36 36 30 63 37 62 33 34 62 74d2a22660c7b34b
5e20: 38 62 62 64 38 35 66 33 63 32 39 63 62 61 66 62 8bbd85f3c29cbafb
5e30: 63 62 31 62 34 65 37 22 0a 0a 2f 2a 0a 2a 2a 20 cb1b4e7"../*.**
5e40: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
5e50: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
5e60: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 on Numbers.** KE
5e70: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
5e80: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 version, sqlite3
5e90: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 _sourceid.**.**
5ea0: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 These interfaces
5eb0: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d provide the sam
5ec0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
5ed0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 the [SQLITE_VER
5ee0: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 SION],.** [SQLIT
5ef0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
5f00: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 ], and [SQLITE_S
5f10: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
5f20: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a rocessor macros.
5f30: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 ** but are assoc
5f40: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c iated with the l
5f50: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f ibrary instead o
5f60: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c f the header fil
5f70: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a e. ^(Cautious.*
5f80: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 * programmers mi
5f90: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 ght include asse
5fa0: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 rt() statements
5fb0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 in their applica
5fc0: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 tion to.** verif
5fd0: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 y that values re
5fe0: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
5ff0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 interfaces match
6000: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a the macros in.*
6010: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e * the header, an
6020: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 d thus insure th
6030: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
6040: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 on is.** compile
6050: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 d with matching
6060: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 library and head
6070: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 er files..**.**
6080: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
6090: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c >.** assert( sql
60a0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
60b0: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 number()==SQLITE
60c0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
60d0: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 );.** assert( st
60e0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 rcmp(sqlite3_sou
60f0: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 rceid(),SQLITE_S
6100: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a OURCE_ID)==0 );.
6110: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d ** assert( strcm
6120: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 p(sqlite3_libver
6130: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 sion(),SQLITE_VE
6140: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 RSION)==0 );.**
6150: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
6160: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te>)^.**.** ^The
6170: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
6180: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 [] string consta
6190: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 nt contains the
61a0: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f text of [SQLITE_
61b0: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 VERSION].** macr
61c0: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 o. ^The sqlite3
61d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 _libversion() fu
61e0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
61f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
6200: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 ** to the sqlite
6210: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
6220: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
6230: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
6240: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 sion().** functi
6250: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 on is provided f
6260: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 or use in DLLs s
6270: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 ince DLL users u
6280: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 sually do not ha
6290: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 ve.** direct acc
62a0: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f ess to string co
62b0: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 nstants within t
62c0: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a he DLL. ^The.**
62d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
62e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e ion_number() fun
62f0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e ction returns an
6300: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 integer equal t
6310: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 o.** [SQLITE_VER
6320: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e SION_NUMBER]. ^
6330: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 The sqlite3_sour
6340: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 ceid() function
6350: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f returns .** a po
6360: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e inter to a strin
6370: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 g constant whose
6380: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 value is the sa
6390: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 me as the .** [S
63a0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
63b0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
63c0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 macro..**.** See
63d0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 also: [sqlite_v
63e0: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
63f0: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
6400: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
6410: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c I const char sql
6420: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d ite3_version[] =
6430: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b SQLITE_VERSION;
6440: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
6450: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
6460: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 libversion(void)
6470: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
6480: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
6490: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b _sourceid(void);
64a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
64b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
64c0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
64d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
64e0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
64f0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f ry Compilation O
6500: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 ptions Diagnosti
6510: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 cs.**.** ^The sq
6520: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
6530: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 ion_used() funct
6540: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ion returns 0 or
6550: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 1 .** indicatin
6560: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 g whether the sp
6570: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 ecified option w
6580: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a as defined at .*
6590: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 * compile time.
65a0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 ^The SQLITE_ pr
65b0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 efix may be omit
65c0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a ted from the .**
65d0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 option name pas
65e0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 sed to sqlite3_c
65f0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
6600: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 d(). .**.** ^Th
6610: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c e sqlite3_compil
6620: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 eoption_get() fu
6630: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 nction allows it
6640: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 erating.** over
6650: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 the list of opti
6660: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 ons that were de
6670: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 fined at compile
6680: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 time by.** retu
6690: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 rning the N-th c
66a0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 ompile time opti
66b0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 on string. ^If
66c0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
66d0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f e,.** sqlite3_co
66e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
66f0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
6700: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
6710: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 SQLITE_ .** pref
6720: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 ix is omitted fr
6730: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 om any strings r
6740: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 eturned by .** s
6750: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
6760: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a tion_get()..**.*
6770: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 * ^Support for t
6780: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 he diagnostic fu
6790: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f nctions sqlite3_
67a0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
67b0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ed().** and sqli
67c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
67d0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f n_get() may be o
67e0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 mitted by specif
67f0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 ying the .** [SQ
6800: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
6810: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f EOPTION_DIAGS] o
6820: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 ption at compile
6830: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 time..**.** See
6840: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 also: SQL funct
6850: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d ions [sqlite_com
6860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
6870: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
6880: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
6890: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b get()] and the [
68a0: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 compile_options
68b0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e pragma]..*/.#ifn
68c0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
68d0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
68e0: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 AGS.SQLITE_API i
68f0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 nt sqlite3_compi
6900: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f leoption_used(co
6910: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 nst char *zOptNa
6920: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 me);.SQLITE_API
6930: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
6940: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
6950: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
6960: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
6970: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
6980: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
6990: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
69a0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
69b0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
69c0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
69d0: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
69e0: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
69f0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
6a00: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
6a10: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
6a20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
6a30: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
6a40: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
6a50: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
6a60: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
6a70: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
6a80: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
6a90: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
6aa0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
6ab0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
6ac0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
6ad0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
6ae0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
6af0: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
6b00: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
6b10: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
6b20: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
6b30: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
6b40: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
6b50: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
6b60: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
6b70: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
6b80: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
6b90: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
6ba0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
6bb0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
6bc0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
6bd0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
6be0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
6bf0: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
6c00: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
6c10: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
6c20: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
6c30: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
6c40: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
6c50: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
6c60: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
6c70: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
6c80: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
6c90: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
6ca0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
6cb0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
6cc0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
6cd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
6ce0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
6cf0: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
6d00: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
6d10: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
6d20: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
6d30: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
6d40: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
6d50: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
6d60: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
6d70: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
6d80: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
6d90: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
6da0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
6db0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
6dc0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
6dd0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
6de0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
6df0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
6e00: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
6e10: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
6e20: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
6e30: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
6e40: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
6e50: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
6e60: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
6e70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
6e80: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
6e90: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
6ea0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
6eb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
6ec0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
6ed0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
6ee0: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 _MUTEX]. ^(The
6ef0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
6f00: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 the.** sqlite3_t
6f10: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
6f20: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 tion shows only
6f30: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 the compile-time
6f40: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 setting of.** t
6f50: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f hread safety, no
6f60: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 t any run-time c
6f70: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 hanges to that s
6f80: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a etting made by.*
6f90: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 * sqlite3_config
6fa0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 (). In other wor
6fb0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ds, the return v
6fc0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
6fd0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 3_threadsafe().*
6fe0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 * is unchanged b
6ff0: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 y calls to sqlit
7000: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a e3_config().)^.*
7010: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 *.** See the [th
7020: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f reading mode] do
7030: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
7040: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
7050: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 mation..*/.SQLIT
7060: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
7070: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 3_threadsafe(voi
7080: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
7090: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
70a0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a nnection Handle.
70b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 ** KEYWORDS: {da
70c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
70d0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e n} {database con
70e0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 nections}.**.**
70f0: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 Each open SQLite
7100: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 database is rep
7110: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f resented by a po
7120: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
7130: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f ance of.** the o
7140: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 paque structure
7150: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e named "sqlite3".
7160: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 It is useful t
7170: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 o think of an sq
7180: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 lite3.** pointer
7190: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 as an object.
71a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 The [sqlite3_ope
71b0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
71c0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a pen16()], and.**
71d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
71e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
71f0: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 are its construc
7200: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 tors, and [sqlit
7210: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 e3_close()].** a
7220: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
7230: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 e_v2()] are its
7240: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 destructors. Th
7250: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 ere are many oth
7260: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 er.** interfaces
7270: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 (such as.** [sq
7280: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
7290: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
72a0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
72b0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
72c0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
72d0: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 ] to name but th
72e0: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 ree) that are me
72f0: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 thods on an.** s
7300: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a qlite3 object..*
7310: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
7320: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
7330: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
7340: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 F: 64-Bit Intege
7350: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f r Types.** KEYWO
7360: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 RDS: sqlite_int6
7370: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 4 sqlite_uint64.
7380: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
7390: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d ere is no cross-
73a0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 platform way to
73b0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 specify 64-bit i
73c0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 nteger types.**
73d0: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 SQLite includes
73e0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d typedefs for 64-
73f0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 bit signed and u
7400: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 nsigned integers
7410: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
7420: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
7430: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 lite3_uint64 are
7440: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 the preferred t
7450: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e ype definitions.
7460: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 .** The sqlite_i
7470: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
7480: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 uint64 types are
7490: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
74a0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
74b0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a atibility only..
74c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
74d0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
74e0: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 ite_int64 types
74f0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
7500: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 r values.** betw
7510: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 een -92233720368
7520: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 54775808 and +92
7530: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 2337203685477580
7540: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 7 inclusive. ^T
7550: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 he.** sqlite3_ui
7560: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
7570: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e uint64 types can
7580: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 store integer v
7590: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 alues .** betwee
75a0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 n 0 and +1844674
75b0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 4073709551615 in
75c0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 clusive..*/.#ifd
75d0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
75e0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 TYPE. typedef S
75f0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
7600: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
7610: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
7620: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 d SQLITE_INT64_T
7630: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 YPE sqlite_uint6
7640: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 4;.#elif defined
7650: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 (_MSC_VER) || de
7660: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 fined(__BORLANDC
7670: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f __). typedef __
7680: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 int64 sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
76a0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 signed __int64 s
76b0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
76c0: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f lse. typedef lo
76d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
76e0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
76f0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e def unsigned lon
7700: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
7710: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 e_uint64;.#endif
7720: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
7730: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e int64 sqlite3_in
7740: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c t64;.typedef sql
7750: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 ite_uint64 sqlit
7760: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a e3_uint64;../*.*
7770: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 * If compiling f
7780: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 or a processor t
7790: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 hat lacks floati
77a0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 ng point support
77b0: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 ,.** substitute
77c0: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 integer for floa
77d0: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 ting-point..*/.#
77e0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
77f0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
7800: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 .# define double
7810: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 sqlite3_int64.#
7820: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
7830: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 I3REF: Closing A
7840: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
7850: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tion.**.** ^The
7860: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
7870: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
7880: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 e_v2() routines
7890: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a are destructors.
78a0: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 ** for the [sqli
78b0: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 te3] object..**
78c0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 ^Calls to sqlite
78d0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 3_close() and sq
78e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
78f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
7900: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c K if.** the [sql
7910: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
7920: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 successfully des
7930: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 troyed and all a
7940: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 ssociated.** res
7950: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c ources are deall
7960: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ocated..**.** ^I
7970: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
7980: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 onnection is ass
7990: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 ociated with unf
79a0: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 inalized prepare
79b0: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 d.** statements
79c0: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
79d0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a lite3_backup obj
79e0: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 ects then sqlite
79f0: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 3_close().** wil
7a00: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 l leave the data
7a10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
7a20: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 open and return
7a30: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
7a40: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c * ^If sqlite3_cl
7a50: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c ose_v2() is call
7a60: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 ed with unfinali
7a70: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 zed prepared sta
7a80: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 tements.** and u
7a90: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 nfinished sqlite
7aa0: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 3_backups, then
7ab0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
7ac0: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a nection becomes.
7ad0: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 ** an unusable "
7ae0: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 zombie" which wi
7af0: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
7b00: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
7b10: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 when the.** last
7b20: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
7b30: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
7b40: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c or the last sql
7b50: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a ite3_backup is.*
7b60: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 * finished. The
7b70: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
7b80: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
7b90: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
7ba0: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c e with.** host l
7bb0: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 anguages that ar
7bc0: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 e garbage collec
7bd0: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 ted, and where t
7be0: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 he order in whic
7bf0: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 h.** destructors
7c00: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 are called is a
7c10: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 rbitrary..**.**
7c20: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
7c30: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e uld [sqlite3_fin
7c40: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
7c50: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 ] all [prepared
7c60: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 statements],.**
7c70: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
7c80: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c ose | close] all
7c90: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
7ca0: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
7cb0: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 3_backup_finish
7cc0: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 | finish] all [s
7cd0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
7ce0: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 bjects associate
7cf0: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 d.** with the [s
7d00: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
7d10: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
7d20: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
7d30: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 object. ^If.**
7d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
7d50: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 () is called on
7d60: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
7d70: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 ection] that sti
7d80: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 ll has.** outsta
7d90: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 nding [prepared
7da0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c statements], [BL
7db0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 OB handles], and
7dc0: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f /or.** [sqlite3_
7dd0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 backup] objects
7de0: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 then it returns
7df0: 53 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 SQLITE_OK but th
7e00: 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a e deallocation.*
7e10: 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 * of resources i
7e20: 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c s deferred until
7e30: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
7e40: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f tatements], [BLO
7e50: 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 B handles],.** a
7e60: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b nd [sqlite3_back
7e70: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 up] objects are
7e80: 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a also destroyed..
7e90: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 **.** ^If an [sq
7ea0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 lite3] object is
7eb0: 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 destroyed while
7ec0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
7ed0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
7ee0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
7ef0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
7f00: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
7f10: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
7f20: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
7f30: 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 (C)] and [sqlite
7f40: 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 3_close_v2(C)].*
7f50: 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 * must be either
7f60: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
7f70: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
7f80: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
7f90: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 r obtained.** fr
7fa0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
7fb0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
7fc0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b en16()], or.** [
7fd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
7fe0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
7ff0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
8000: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
8010: 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 e3_close() or sq
8020: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
8030: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
8040: 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 nter.** argument
8050: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
8060: 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f o-op..*/.SQLITE_
8070: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
8080: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b close(sqlite3*);
8090: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
80a0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
80b0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
80c0: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
80d0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
80e0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
80f0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
8100: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
8110: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
8120: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
8130: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
8140: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
8150: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
8160: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
8170: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
8180: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
8190: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
81a0: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
81b0: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
81c0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
81d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
81e0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
81f0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 nce wrapper arou
8200: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 nd.** [sqlite3_p
8210: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
8220: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
8230: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
8240: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 alize()],.** tha
8250: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c t allows an appl
8260: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d ication to run m
8270: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e ultiple statemen
8280: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 ts of SQL.** wit
8290: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 hout having to u
82a0: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f se a lot of C co
82b0: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de. .**.** ^The
82c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
82d0: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 nterface runs ze
82e0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 ro or more UTF-8
82f0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d encoded,.** sem
8300: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 icolon-separate
8310: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
8320: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 assed into its 2
8330: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 nd argument,.**
8340: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
8350: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
8360: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 connection] pass
8370: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 ed in as its 1st
8380: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e .** argument. ^
8390: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
83a0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 function of the
83b0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 3rd argument to.
83c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
83d0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 ) is not NULL, t
83e0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
83f0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c d for each resul
8400: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 t row.** coming
8410: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 out of the evalu
8420: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
8430: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 nts. ^The 4th a
8440: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
8450: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
8460: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
8470: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
8480: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
8490: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
84a0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
84b0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
84c0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
84d0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
84e0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
84f0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
8500: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
8510: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
8520: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
8530: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
8540: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
8550: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
8560: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
8570: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
8580: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
8590: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
85a0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
85b0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
85c0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
85d0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
85e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
85f0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
8600: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
8610: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
8620: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
8630: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
8640: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
8650: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
8660: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
8670: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
8680: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
8690: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
86a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
86b0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
86c0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
86d0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
86e0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
86f0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
8700: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
8710: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f f.** of sqlite3_
8720: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
8730: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
8740: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
8750: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
8760: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
8770: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
8780: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
8790: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
87a0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
87b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
87c0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
87d0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
87e0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
87f0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
8800: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
8810: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
8820: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
8830: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
8840: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
8850: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
8860: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
8870: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
8880: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
8890: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
88a0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
88b0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
88c0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
88d0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
88e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
88f0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
8900: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
8910: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
8920: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
8930: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
8940: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
8950: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
8960: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
8970: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
8980: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
8990: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
89a0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
89b0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
89c0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
89d0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
89e0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
89f0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
8a00: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
8a10: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
8a20: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
8a30: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
8a40: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
8a50: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
8a60: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
8a70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8a80: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
8a90: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
8aa0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
8ab0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
8ac0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
8ad0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
8ae0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
8af0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
8b00: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
8b10: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
8b20: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
8b30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
8b40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
8b50: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
8b60: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
8b70: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
8b80: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
8b90: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
8ba0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
8bb0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
8bc0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
8bd0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
8be0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
8bf0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
8c00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
8c10: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
8c20: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
8c30: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
8c40: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 ation must insur
8c50: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
8c60: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
8c70: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
8c80: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
8c90: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
8ca0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
8cb0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
8cc0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
8cd0: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 lose [database c
8ce0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
8cf0: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 fied by.**
8d00: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
8d10: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
8d20: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 c() while sqlite
8d30: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 3_exec() is runn
8d40: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 ing..** <li> The
8d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8d60: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 t not modify the
8d70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
8d80: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a ext passed into.
8d90: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 ** the 2nd
8da0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
8db0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c ite3_exec() whil
8dc0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
8dd0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
8de0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ul>.*/.SQLITE_
8df0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
8e00: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
8e10: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
8e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8e30: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
8e40: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
8e50: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
8e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8e70: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
8e80: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
8e90: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
8ea0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
8eb0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
8ec0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
8ed0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8f00: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
8f10: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
8f20: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
8f30: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
8f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
8f50: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
8f60: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
8f70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8f80: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
8f90: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
8fa0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
8fb0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
8fc0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
8fd0: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
8fe0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
8ff0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
9000: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
9010: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
9020: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
9030: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
9040: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
9050: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 te success or fa
9060: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 ilure..**.** New
9070: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 error codes may
9080: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
9090: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
90a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 SQLite..**.** Se
90b0: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f e also: [SQLITE_
90c0: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 IOERR_READ | ext
90d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
90e0: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 es],.** [sqlite3
90f0: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 _vtab_on_conflic
9100: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c t()] [SQLITE_ROL
9110: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 LBACK | result c
9120: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e odes]..*/.#defin
9130: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
9140: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
9150: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
9160: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
9170: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
9180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9190: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
91a0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
91b0: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
91c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
91d0: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
91e0: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
91f0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
9200: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
9210: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
9220: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
9230: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
9240: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
9250: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
9260: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
9270: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
9280: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
9290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
92a0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
92b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
92c0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
92d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
92e0: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
92f0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
9300: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
9310: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
9320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
9330: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
9340: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
9350: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
9360: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
9370: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
9380: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
9390: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
93a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
93b0: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
93c0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
93d0: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
93e0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
93f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9400: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
9410: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
9420: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
9430: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
9440: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
9450: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
9460: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
9470: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
9480: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
9490: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
94a0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 12 /* Unknow
94b0: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 n opcode in sqli
94c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
94d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
94e0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
94f0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
9500: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
9510: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
9520: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
9530: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
9540: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
9550: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
9560: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
9570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
9580: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
9590: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
95a0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
95b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
95c0: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
95d0: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
95e0: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
95f0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
9600: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
9610: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
9620: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
9630: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
9640: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
9650: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
9660: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
9670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
9680: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
9690: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
96a0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
96b0: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
96c0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
96d0: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
96e0: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
96f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9700: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
9710: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
9720: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
9730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
9740: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
9750: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
9760: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
9770: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
9780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
9790: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
97a0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
97b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
97c0: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
97d0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
97e0: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
97f0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
9800: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
9810: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
9820: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
9830: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
9840: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
9850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9860: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
9870: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
9880: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
9890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
98a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
98b0: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
98c0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
98d0: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
98e0: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
98f0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
9900: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
9910: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
9920: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
9930: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
9940: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
9950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
9960: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
9970: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
9980: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 S: {extended err
9990: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 or code} {extend
99a0: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a ed error codes}.
99b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 ** KEYWORDS: {ex
99c0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
99d0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 de} {extended re
99e0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
99f0: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 * In its default
9a00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
9a10: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
9a20: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
9a30: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 f 26 integer.**
9a40: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 [SQLITE_OK | res
9a50: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
9a60: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
9a70: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
9a80: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
9a90: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
9aa0: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
9ab0: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
9ac0: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
9ad0: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
9ae0: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
9af0: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
9b00: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
9b10: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
9b20: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
9b30: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
9b40: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
9b50: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 3.3.8 and later)
9b60: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 include.** supp
9b70: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ort for addition
9b80: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 al result codes
9b90: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 that provide mor
9ba0: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 e detailed infor
9bb0: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
9bc0: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 errors. The exte
9bd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9be0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 s are enabled or
9bf0: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
9c00: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
9c10: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
9c20: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
9c30: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
9c40: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
9c50: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f PI..**.** Some o
9c60: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 f the available
9c70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
9c80: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 codes are listed
9c90: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 here..** One ma
9ca0: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d y expect the num
9cb0: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 ber of extended
9cc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c result codes wil
9cd0: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f l be expand.** o
9ce0: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 ver time. Softw
9cf0: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 are that uses ex
9d00: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
9d10: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 des should expec
9d20: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 t.** to see new
9d30: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 result codes in
9d40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
9d50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
9d60: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 The SQLITE_OK r
9d70: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 esult code will
9d80: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 never be extende
9d90: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 d. It will alwa
9da0: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 ys.** be exactly
9db0: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e zero..*/.#defin
9dc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
9dd0: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
9de0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
9df0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
9e00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
9e10: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 ORT_READ
9e20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9e30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
9e40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 SQLITE_IOERR_WRI
9e50: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 TE (
9e60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
9e70: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
9e80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e QLITE_IOERR_FSYN
9e90: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 C (S
9ea0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 QLITE_IOERR | (4
9eb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
9ec0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 LITE_IOERR_DIR_F
9ed0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 SYNC (SQ
9ee0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c LITE_IOERR | (5<
9ef0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
9f00: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 ITE_IOERR_TRUNCA
9f10: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c TE (SQL
9f20: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c ITE_IOERR | (6<<
9f30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
9f40: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 TE_IOERR_FSTAT
9f50: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
9f60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 TE_IOERR | (7<<8
9f70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
9f80: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 E_IOERR_UNLOCK
9f90: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
9fa0: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 E_IOERR | (8<<8)
9fb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
9fc0: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 _IOERR_RDLOCK
9fd0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
9fe0: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 _IOERR | (9<<8))
9ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a000: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 IOERR_DELETE
a010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a020: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 IOERR | (10<<8))
a030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a040: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 IOERR_BLOCKED
a050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a060: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 IOERR | (11<<8))
a070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a080: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 IOERR_NOMEM
a090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a0a0: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 IOERR | (12<<8))
a0b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a0c0: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 IOERR_ACCESS
a0d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a0e0: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 IOERR | (13<<8))
a0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a100: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 IOERR_CHECKRESER
a110: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f VEDLOCK (SQLITE_
a120: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 IOERR | (14<<8))
a130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a140: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 IOERR_LOCK
a150: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a160: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 IOERR | (15<<8))
a170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a180: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 IOERR_CLOSE
a190: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a1a0: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 IOERR | (16<<8))
a1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a1c0: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 IOERR_DIR_CLOSE
a1d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a1e0: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 IOERR | (17<<8))
a1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a200: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 IOERR_SHMOPEN
a210: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a220: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 IOERR | (18<<8))
a230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a240: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 IOERR_SHMSIZE
a250: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a260: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 IOERR | (19<<8))
a270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a280: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 IOERR_SHMLOCK
a290: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a2a0: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 IOERR | (20<<8))
a2b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a2c0: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 IOERR_SHMMAP
a2d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a2e0: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 IOERR | (21<<8))
a2f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a300: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 IOERR_SEEK
a310: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
a320: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 IOERR | (22<<8))
a330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a340: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 IOERR_DELETE_NOE
a350: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f NT (SQLITE_
a360: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 IOERR | (23<<8))
a370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a380: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
a390: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f HE (SQLITE_
a3a0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 LOCKED | (1<<8)
a3b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
a3c0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 _BUSY_RECOVERY
a3d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
a3e0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 _BUSY | (1<<8
a3f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a400: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d E_CANTOPEN_NOTEM
a410: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 PDIR (SQLIT
a420: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c E_CANTOPEN | (1<
a430: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
a440: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 ITE_CANTOPEN_ISD
a450: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c IR (SQL
a460: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
a470: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
a480: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 QLITE_CANTOPEN_F
a490: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 ULLPATH (S
a4a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
a4b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
a4c0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f SQLITE_CORRUPT_
a4d0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 VTAB
a4e0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 (SQLITE_CORRUPT
a4f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
a500: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
a510: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
a520: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
a530: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 Y | (1<<8)).#def
a540: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
a550: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 NLY_CANTLOCK
a560: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
a570: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 NLY | (2<<8)).#d
a580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
a590: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 DONLY_ROLLBACK
a5a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
a5b0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a DONLY | (3<<8)).
a5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
a5d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 BORT_ROLLBACK
a5e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
a5f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 BORT | (2<<8)).#
a600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
a610: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 NSTRAINT_CHECK
a620: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
a630: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 NSTRAINT | (1<<8
a640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a650: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d E_CONSTRAINT_COM
a660: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 MITHOOK (SQLIT
a670: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
a680: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
a690: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
a6a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 _FOREIGNKEY (S
a6b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
a6c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
a6d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
a6e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 AINT_FUNCTION
a6f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
a700: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 AINT | (4<<8)).#
a710: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
a720: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c NSTRAINT_NOTNULL
a730: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
a740: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 NSTRAINT | (5<<8
a750: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a760: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 E_CONSTRAINT_PRI
a770: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 MARYKEY (SQLIT
a780: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
a790: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
a7a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
a7b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 _TRIGGER (S
a7c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
a7d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
a7e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
a7f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 AINT_UNIQUE
a800: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
a810: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 AINT | (8<<8)).#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
a830: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 NSTRAINT_VTAB
a840: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
a850: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 NSTRAINT | (9<<8
a860: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
a870: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
a880: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
a890: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
a8a0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
a8b0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
a8c0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
a8d0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
a8e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
a8f0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
a900: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
a910: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
a920: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
a930: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 n] method..*/.#d
a940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
a950: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
a960: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 0x00000001 /
a970: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
a980: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
a990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
a9a0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
a9b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 0x00000002 /
a9c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
a9d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
a9e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
a9f0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
aa00: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 0x00000004 /
aa10: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
aa20: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
aa30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aa40: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
aa50: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 0x00000008 /
aa60: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
aa70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aa80: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
aa90: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 0x00000010 /
aaa0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
aab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aac0: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 N_AUTOPROXY
aad0: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 0x00000020 /
aae0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
aaf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ab00: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 N_URI
ab10: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 0x00000040 /
ab20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ab30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
ab40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ab50: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 N_MEMORY
ab60: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 0x00000080 /
ab70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ab80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
ab90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aba0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
abb0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 0x00000100 /
abc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
abd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
abe0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
abf0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 0x00000200 /
ac00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
ac10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ac20: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
ac30: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 0x00000400 /
ac40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
ac50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ac60: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
ac70: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 0x00000800 /
ac80: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
ac90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aca0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
acb0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 0x00001000 /
acc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
acd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ace0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
acf0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 0x00002000 /
ad00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
ad10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ad20: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
ad30: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 0x00004000 /
ad40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
ad50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ad60: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
ad70: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 0x00008000 /
ad80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ad90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
ada0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
adb0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 N_FULLMUTEX
adc0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 0x00010000 /
add0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ade0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
adf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ae00: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 N_SHAREDCACHE
ae10: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 0x00020000 /
ae20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ae30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
ae40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
ae50: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 N_PRIVATECACHE
ae60: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 0x00040000 /
ae70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
ae80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
ae90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
aea0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 N_WAL
aeb0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 0x00080000 /
aec0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f * VFS only */../
aed0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 * Reserved:
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
aef0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 0x00F00000 *
af00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
af10: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 F: Device Charac
af20: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 teristics.**.**
af30: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
af40: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
af50: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 d of the [sqlite
af60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
af70: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 object returns
af80: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
af90: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 is a vector of
afa0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
afb0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
afc0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
afd0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
afe0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
aff0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
b000: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
b010: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
b020: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
b030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
b040: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
b050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
b060: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
b070: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
b080: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
b090: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
b0a0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
b0b0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
b0c0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
b0d0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
b0e0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
b0f0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
b100: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
b110: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
b120: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
b130: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
b140: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
b150: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
b160: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
b170: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
b180: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
b190: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
b1a0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
b1b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
b1c0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
b1d0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
b1e0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
b1f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
b200: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
b210: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
b220: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
b230: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
b240: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
b250: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
b260: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 to xWrite(). T
b270: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
b280: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
b290: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 ITE property mea
b2a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 ns that.** after
b2b0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e reboot followin
b2c0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 g a crash or pow
b2d0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c er loss, the onl
b2e0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 y bytes in a.**
b2f0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 file that were w
b300: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 ritten at the ap
b310: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 plication level
b320: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 might have chang
b330: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 ed.** and that a
b340: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 djacent bytes, e
b350: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e ven bytes within
b360: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 the same sector
b370: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 are.** guarante
b380: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 ed to be unchang
b390: 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ed..*/.#define S
b3a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
b3b0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 IC
b3c0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 0x00000001.#d
b3d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
b3e0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 AP_ATOMIC512
b3f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
b400: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
b410: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
b420: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 1K
b430: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 0x00000004.#def
b440: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
b450: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 _ATOMIC2K
b460: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
b470: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 08.#define SQLIT
b480: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
b490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
b4a0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
b4b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
b4c0: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 TOMIC8K
b4d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
b4e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b4f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
b500: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
b510: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 0000040.#define
b520: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
b530: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 MIC32K
b540: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 0x00000080.#
b550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
b560: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 CAP_ATOMIC64K
b570: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
b580: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00100.#define SQ
b590: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
b5a0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 APPEND
b5b0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
b5c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
b5d0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
b5e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
b5f0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 400.#define SQLI
b600: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
b610: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 ABLE_WHEN_OPEN
b620: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 0x00000800.#defi
b630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
b640: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
b650: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 ITE 0x0000100
b660: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
b670: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 F: File Locking
b680: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c Levels.**.** SQL
b690: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 ite uses one of
b6a0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
b6b0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
b6c0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 nd.** argument t
b6d0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 o calls it makes
b6e0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 to the xLock()
b6f0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 and xUnlock() me
b700: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b thods.** of an [
b710: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
b720: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 ds] object..*/.#
b730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
b740: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 CK_NONE
b750: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
b760: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 E_LOCK_SHARED
b770: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
b780: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
b790: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 VED 2.#defi
b7a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 ne SQLITE_LOCK_P
b7b0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 ENDING 3.#
b7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
b7d0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 CK_EXCLUSIVE
b7e0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 4../*.** CAPI3R
b7f0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 EF: Synchronizat
b800: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a ion Type Flags.*
b810: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 *.** When SQLite
b820: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 invokes the xSy
b830: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 nc() method of a
b840: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
b850: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
b860: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 it uses a combi
b870: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 nation of.** the
b880: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 se integer value
b890: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 s as the second
b8a0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
b8b0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f When the SQLITE_
b8c0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c SYNC_DATAONLY fl
b8d0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d ag is used, it m
b8e0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a eans that the.**
b8f0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 sync operation
b900: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c only needs to fl
b910: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 ush data to mass
b920: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 storage. Inode
b930: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
b940: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 need not be flus
b950: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 hed. If the lowe
b960: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 r four bits of t
b970: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c he flag.** equal
b980: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
b990: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 MAL, that means
b9a0: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 to use normal fs
b9b0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e ync() semantics.
b9c0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 .** If the lower
b9d0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c four bits equal
b9e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
b9f0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a L, that means.**
ba00: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 to use Mac OS X
ba10: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 style fullsync
ba20: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 instead of fsync
ba30: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 ()..**.** Do not
ba40: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c confuse the SQL
ba50: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
ba60: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f and SQLITE_SYNC_
ba70: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 FULL flags.** wi
ba80: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 th the [PRAGMA s
ba90: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d ynchronous]=NORM
baa0: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 AL and [PRAGMA s
bab0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c ynchronous]=FULL
bac0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 .** settings. T
bad0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 he [synchronous
bae0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e pragma] determin
baf0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f es when calls to
bb00: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 the.** xSync VF
bb10: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 S method occur a
bb20: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f nd applies unifo
bb30: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 rmly across all
bb40: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 platforms..** Th
bb50: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
bb60: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
bb70: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 SYNC_FULL flags
bb80: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a determine how.**
bb90: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 energetic or ri
bba0: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 gorous or forcef
bbb0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 ul the sync oper
bbc0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a ations are and.*
bbd0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 * only make a di
bbe0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 fference on Mac
bbf0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 OSX for the defa
bc00: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e ult SQLite code.
bc10: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 .** (Third-party
bc20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
bc30: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 ions might also
bc40: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
bc50: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 tion.** between
bc60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
bc70: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
bc80: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f NC_FULL, but amo
bc90: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 ng the.** operat
bca0: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 ing systems nati
bcb0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 vely supported b
bcc0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d y SQLite, only M
bcd0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 ac OSX.** cares
bce0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 about the differ
bcf0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e ence.).*/.#defin
bd00: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
bd10: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 RMAL 0x00
bd20: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
bd30: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 TE_SYNC_FULL
bd40: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 0x00003.#d
bd50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
bd60: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 C_DATAONLY
bd70: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 0x00010../*.** C
bd80: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
bd90: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 rface Open File
bda0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 Handle.**.** An
bdb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
bdc0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
bdd0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e an open file in
bde0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
bdf0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 3_vfs | OS inter
be00: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e face layer]. In
be10: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 dividual OS inte
be20: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 rface.** impleme
be30: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a ntations will.**
be40: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 want to subclas
be50: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 s this object by
be60: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 appending addit
be70: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 ional fields.**
be80: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 for their own us
be90: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 e. The pMethods
bea0: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e entry is a poin
beb0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 ter to an.** [sq
bec0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
bed0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 ] object that de
bee0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f fines methods fo
bef0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 r performing.**
bf00: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f I/O operations o
bf10: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e n the open file.
bf20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
bf30: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ct sqlite3_file
bf40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 sqlite3_file;.st
bf50: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
bf60: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 e {. const stru
bf70: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
bf80: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b thods *pMethods;
bf90: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
bfa0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f an open file */
bfb0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
bfc0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
bfd0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d e File Virtual M
bfe0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a ethods Object.**
bff0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f .** Every file o
c000: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 pened by the [sq
c010: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
c020: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 method populate
c030: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s an.** [sqlite3
c040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f _file] object (o
c050: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 r, more commonly
c060: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 , a subclass of
c070: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
c080: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 file] object) wi
c090: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 th a pointer to
c0a0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
c0b0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 his object..** T
c0c0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
c0d0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 es the methods u
c0e0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 sed to perform v
c0f0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e arious operation
c100: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 s.** against the
c110: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 open file repre
c120: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 sented by the [s
c130: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
c140: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ect..**.** If th
c150: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
c160: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 Open] method set
c170: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 s the sqlite3_fi
c180: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
c190: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e ent .** to a non
c1a0: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
c1b0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
c1c0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 io_methods.xClos
c1d0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 e method.** may
c1e0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 be invoked even
c1f0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f if the [sqlite3_
c200: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 vfs.xOpen] repor
c210: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c ted that it fail
c220: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 ed. The.** only
c230: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 way to prevent
c240: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 a call to xClose
c250: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
c260: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 led [sqlite3_vfs
c270: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f .xOpen].** is fo
c280: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 r the [sqlite3_v
c290: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 fs.xOpen] to set
c2a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
c2b0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 e.pMethods eleme
c2c0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a nt.** to NULL..*
c2d0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
c2e0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 rgument to xSync
c2f0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b may be one of [
c300: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
c310: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 AL] or.** [SQLIT
c320: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 E_SYNC_FULL]. T
c330: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 he first choice
c340: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 is the normal fs
c350: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ync()..** The se
c360: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 cond choice is a
c370: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
c380: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b fullsync. The [
c390: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
c3a0: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 ONLY].** flag ma
c3b0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 y be ORed in to
c3c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e indicate that on
c3d0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 ly the data of t
c3e0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e he file.** and n
c3f0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 ot its inode nee
c400: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e ds to be synced.
c410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 .**.** The integ
c420: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f er values to xLo
c430: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
c440: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a () are one of.**
c450: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
c460: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
c470: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
c480: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a E_LOCK_SHARED],.
c490: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c4a0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a LOCK_RESERVED],.
c4b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c4c0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
c4d0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
c4e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
c4f0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 ]..** </ul>.** x
c500: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 Lock() increases
c510: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f the lock. xUnlo
c520: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 ck() decreases t
c530: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 he lock..** The
c540: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
c550: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 ck() method chec
c560: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 ks whether any d
c570: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
c580: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e on,.** either in
c590: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 this process or
c5a0: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 in some other p
c5b0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 rocess, is holdi
c5c0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a ng a RESERVED,.*
c5d0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 * PENDING, or EX
c5e0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 CLUSIVE lock on
c5f0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 the file. It re
c600: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 turns true.** if
c610: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 such a lock exi
c620: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 sts and false ot
c630: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 herwise..**.** T
c640: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 he xFileControl(
c650: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 ) method is a ge
c660: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 neric interface
c670: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 that allows cust
c680: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d om.** VFS implem
c690: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 entations to dir
c6a0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e ectly control an
c6b0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 open file using
c6c0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
c6d0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
c6e0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 interface. The
c6f0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 second "op" arg
c700: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 ument is an.** i
c710: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 nteger opcode.
c720: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
c730: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 nt is a generic
c740: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 pointer intended
c750: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 to.** point to
c760: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 a structure that
c770: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 may contain arg
c780: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 uments or space
c790: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 in which to.** w
c7a0: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 rite return valu
c7b0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 es. Potential u
c7c0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e ses for xFileCon
c7d0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a trol() might be.
c7e0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 ** functions to
c7f0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 enable blocking
c800: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f locks with timeo
c810: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 uts, to change t
c820: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 he.** locking st
c830: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d rategy (for exam
c840: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 ple to use dot-f
c850: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 ile locks), to i
c860: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 nquire.** about
c870: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 the status of a
c880: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 lock, or to brea
c890: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 k stale locks.
c8a0: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f The SQLite.** co
c8b0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 re reserves all
c8c0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 opcodes less tha
c8d0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 n 100 for its ow
c8e0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c n use..** A [SQL
c8f0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
c900: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 ATE | list of op
c910: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e codes] less than
c920: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 100 is availabl
c930: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f e..** Applicatio
c940: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 ns that define a
c950: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e custom xFileCon
c960: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 trol method shou
c970: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a ld use opcodes.*
c980: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 * greater than 1
c990: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 00 to avoid conf
c9a0: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c licts. VFS impl
c9b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
c9c0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ld.** return [SQ
c9d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 LITE_NOTFOUND] f
c9e0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 or file control
c9f0: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 opcodes that the
ca00: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f y do not.** reco
ca10: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 gnize..**.** The
ca20: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d xSectorSize() m
ca30: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 ethod returns th
ca40: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 e sector size of
ca50: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 the.** device t
ca60: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 hat underlies th
ca70: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 e file. The sec
ca80: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a tor size is the.
ca90: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 ** minimum write
caa0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 that can be per
cab0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 formed without d
cac0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 isturbing.** oth
cad0: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 er bytes in the
cae0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 file. The xDevi
caf0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
cb00: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 s().** method re
cb10: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 turns a bit vect
cb20: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 or describing be
cb30: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a haviors of the.*
cb40: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 * underlying dev
cb50: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ice:.**.** <ul>.
cb60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
cb70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a IOCAP_ATOMIC].**
cb80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
cb90: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a CAP_ATOMIC512].*
cba0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
cbb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a OCAP_ATOMIC1K].*
cbc0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
cbd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a OCAP_ATOMIC2K].*
cbe0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
cbf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a OCAP_ATOMIC4K].*
cc00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
cc10: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a OCAP_ATOMIC8K].*
cc20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
cc30: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a OCAP_ATOMIC16K].
cc40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
cc50: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d IOCAP_ATOMIC32K]
cc60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
cc70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
cc80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
cc90: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
cca0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 END].** <li> [SQ
ccb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
ccc0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a NTIAL].** </ul>.
ccd0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
cce0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
ccf0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
cd00: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
cd10: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
cd20: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
cd30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
cd40: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
cd50: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
cd60: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
cd70: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
cd80: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
cd90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
cda0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
cdb0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
cdc0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
cdd0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
cde0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
cdf0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
ce00: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
ce10: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
ce20: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
ce30: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
ce40: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
ce50: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
ce60: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
ce70: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
ce80: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
ce90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
cea0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
ceb0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
cec0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
ced0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
cee0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
cef0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
cf00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a to xWrite()..**.
cf10: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 ** If xRead() re
cf20: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 turns SQLITE_IOE
cf30: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 RR_SHORT_READ it
cf40: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a must also fill.
cf50: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 ** in the unread
cf60: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 portions of the
cf70: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 buffer with zer
cf80: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a os. A VFS that.
cf90: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f ** fails to zero
cfa0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 -fill short read
cfb0: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 s might seem to
cfc0: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a work. However,.
cfd0: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 ** failure to ze
cfe0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
cff0: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 ads will eventua
d000: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 lly lead to.** d
d010: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 atabase corrupti
d020: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 on..*/.typedef s
d030: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
d040: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
d050: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 _io_methods;.str
d060: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
d070: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 ethods {. int i
d080: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 Version;. int (
d090: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 *xClose)(sqlite3
d0a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
d0b0: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f *xRead)(sqlite3_
d0c0: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e file*, void*, in
d0d0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
d0e0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
d0f0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 int (*xWrite)(sq
d100: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e lite3_file*, con
d110: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 st void*, int iA
d120: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
d130: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
d140: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c (*xTruncate)(sql
d150: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
d160: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b te3_int64 size);
d170: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 . int (*xSync)(
d180: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
d190: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 nt flags);. int
d1a0: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 (*xFileSize)(sq
d1b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
d1c0: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a ite3_int64 *pSiz
d1d0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 e);. int (*xLoc
d1e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
d1f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
d200: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 xUnlock)(sqlite3
d210: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
d220: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 int (*xCheckRese
d230: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 rvedLock)(sqlite
d240: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 3_file*, int *pR
d250: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
d260: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 xFileControl)(sq
d270: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
d280: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 op, void *pArg)
d290: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f ;. int (*xSecto
d2a0: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 rSize)(sqlite3_f
d2b0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
d2c0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
d2d0: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 stics)(sqlite3_f
d2e0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 ile*);. /* Meth
d2f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
d300: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
d310: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 1 */. int (*xSh
d320: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 mMap)(sqlite3_fi
d330: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e le*, int iPg, in
d340: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 t pgsz, int, voi
d350: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 d volatile**);.
d360: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 int (*xShmLock)
d370: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
d380: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 int offset, int
d390: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 n, int flags);.
d3a0: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 void (*xShmBarr
d3b0: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ier)(sqlite3_fil
d3c0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 e*);. int (*xSh
d3d0: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f mUnmap)(sqlite3_
d3e0: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 file*, int delet
d3f0: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 eFlag);. /* Met
d400: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
d410: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
d420: 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 2 */. /* Addit
d430: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 ional methods ma
d440: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
d450: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f ture releases */
d460: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
d470: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 REF: Standard Fi
d480: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 le Control Opcod
d490: 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 es.**.** These i
d4a0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
d4b0: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 are opcodes for
d4c0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
d4d0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 l method.** of t
d4e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
d4f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
d500: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 nd for the [sqli
d510: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
d520: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
d530: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
d540: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
d550: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
d560: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
d570: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
d580: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
d590: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
d5a0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
d5b0: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
d5c0: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
d5d0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
d5e0: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
d5f0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
d600: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
d610: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
d620: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
d630: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
d640: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
d650: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
d660: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
d670: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
d680: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
d690: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
d6a0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f ng testing and o
d6b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
d6c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
d6d0: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 QLITE_TEST.** is
d6e0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c defined..** <ul
d6f0: 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 >.** <li>[[SQLIT
d700: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
d710: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 T]].** The [SQLI
d720: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
d730: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 NT] opcode is us
d740: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 ed by SQLite to
d750: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 give the VFS.**
d760: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 layer a hint of
d770: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 how large the da
d780: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
d790: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 grow to be duri
d7a0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e ng the.** curren
d7b0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 t transaction.
d7c0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 This hint is not
d7d0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
d7e0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 e accurate but i
d7f0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c t.** is often cl
d800: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c ose. The underl
d810: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 ying VFS might c
d820: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f hoose to preallo
d830: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a cate database.**
d840: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 file space base
d850: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 d on this hint i
d860: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 n order to help
d870: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 writes to the da
d880: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 tabase.** file r
d890: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a un faster..**.**
d8a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d8b0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d NTL_CHUNK_SIZE]]
d8c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
d8d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
d8e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
d8f0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 to request that
d900: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 the VFS.** exte
d910: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 nds and truncate
d920: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
d930: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 ile in chunks of
d940: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 a size specifie
d950: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 d.** by the user
d960: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 . The fourth arg
d970: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
d980: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
d990: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 ] should .** poi
d9a0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 nt to an integer
d9b0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 (type int) cont
d9c0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 aining the new c
d9d0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 hunk-size to use
d9e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 .** for the nomi
d9f0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 nated database.
da00: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 Allocating datab
da10: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 ase file space i
da20: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b n large.** chunk
da30: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 s (say 1MB at a
da40: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 time), may reduc
da50: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 e file-system fr
da60: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a agmentation and.
da70: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f ** improve perfo
da80: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 rmance on some s
da90: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ystems..**.** <l
daa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
dab0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a _FILE_POINTER]].
dac0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
dad0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
dae0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 R] opcode is use
daf0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f d to obtain a po
db00: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
db10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
db20: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
db30: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
db40: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ar database.** c
db50: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 onnection. See
db60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
db70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 e_control()] doc
db80: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a umentation for.*
db90: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 * additional inf
dba0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
dbb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
dbc0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d TL_SYNC_OMITTED]
dbd0: 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 ].** ^(The [SQLI
dbe0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d TE_FCNTL_SYNC_OM
dbf0: 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 ITTED] opcode is
dc00: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
dc10: 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 nally by.** SQLi
dc20: 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 te and sent to a
dc30: 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 ll VFSes in plac
dc40: 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 e of a call to t
dc50: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a he xSync method.
dc60: 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 ** when the data
dc70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
dc80: 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 has [PRAGMA sync
dc90: 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 hronous] set to
dca0: 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 OFF.)^.** Some s
dcb0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 pecialized VFSes
dcc0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
dcd0: 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 l in order to op
dce0: 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a erate correctly.
dcf0: 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 ** when [PRAGMA
dd00: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 synchronous | PR
dd10: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
dd20: 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 =OFF] is set, bu
dd30: 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 t most .** VFSes
dd40: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 do not need thi
dd50: 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f s signal and sho
dd60: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
dd70: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
dd80: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
dd90: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
dda0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
ddb0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
ddc0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 his.** opcode as
ddd0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 doing so may di
dde0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
ddf0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
de00: 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 alized VFSes.**
de10: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
de20: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
de30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
de40: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a IN32_AV_RETRY]].
de50: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
de60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
de70: 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 ETRY] opcode is
de80: 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 used to configur
de90: 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 e automatic.** r
dea0: 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 etry counts and
deb0: 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 intervals for ce
dec0: 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f rtain disk I/O o
ded0: 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 perations for th
dee0: 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 e.** windows [VF
def0: 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 S] in order to p
df00: 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 rovide robustnes
df10: 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 s in the presenc
df20: 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 e of.** anti-vir
df30: 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 us programs. By
df40: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 default, the wi
df50: 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 ndows VFS will r
df60: 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a etry file read,.
df70: 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 ** file write, a
df80: 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f nd file delete o
df90: 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 perations up to
dfa0: 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 10 times, with a
dfb0: 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 delay.** of 25
dfc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 milliseconds bef
dfd0: 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 ore the first re
dfe0: 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 try and with the
dff0: 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e delay increasin
e000: 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 g.** by an addit
e010: 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 ional 25 millise
e020: 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 conds with each
e030: 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 subsequent retry
e040: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
e050: 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 e allows these t
e060: 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 wo values (10 re
e070: 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c tries and 25 mil
e080: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c liseconds of del
e090: 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a ay).** to be adj
e0a0: 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 usted. The valu
e0b0: 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 es are changed f
e0c0: 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 or all database
e0d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 connections.** w
e0e0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 ithin the same p
e0f0: 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 rocess. The arg
e100: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
e110: 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f er to an array o
e120: 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 f two.** integer
e130: 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 s where the firs
e140: 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 t integer i the
e150: 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 new retry count
e160: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a and the second.*
e170: 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 * integer is the
e180: 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 delay. If eith
e190: 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 er integer is ne
e1a0: 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
e1b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e setting.** is n
e1c0: 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 ot changed but i
e1d0: 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 nstead the prior
e1e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 value of that s
e1f0: 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 etting is writte
e200: 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 n.** into the ar
e210: 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 ray entry, allow
e220: 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 ing the current
e230: 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 retry settings t
e240: 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 o be.** interrog
e250: 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 ated. The zDbNa
e260: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
e270: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c ignored..**.** <
e280: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
e290: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a L_PERSIST_WAL]].
e2a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
e2b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
e2c0: 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 L] opcode is use
e2d0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
e2e0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
e2f0: 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 ent [WAL | Write
e300: 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 Ahead Log] sett
e310: 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ing. By default
e320: 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a , the auxiliary.
e330: 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c ** write ahead l
e340: 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 og and shared me
e350: 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 mory files used
e360: 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 for transaction
e370: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 control.** are a
e380: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
e390: 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 eted when the la
e3a0: 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 test connection
e3b0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a to the database.
e3c0: 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 ** closes. Sett
e3d0: 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 ing persistent W
e3e0: 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 AL mode causes t
e3f0: 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 hose files to pe
e400: 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 rsist after.** c
e410: 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e lose. Persistin
e420: 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 g the files is u
e430: 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 seful when other
e440: 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 processes that
e450: 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 do not.** have w
e460: 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 rite permission
e470: 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 on the directory
e480: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
e490: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
e4a0: 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 nt.** to read th
e4b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
e4c0: 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 as the WAL and
e4d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
e4e0: 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a les must exist.*
e4f0: 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 * in order for t
e500: 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 he database to b
e510: 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 e readable. The
e520: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
e530: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
e540: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
e550: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
e560: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
e570: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
e580: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
e590: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
e5a0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 ble persistent W
e5b0: 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 AL mode or 1 to
e5c0: 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e enable persisten
e5d0: 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 t.** WAL mode.
e5e0: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
e5f0: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
e600: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
e610: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
e620: 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 WAL persistence
e630: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
e640: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
e650: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
e660: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
e670: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
e680: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
e690: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
e6a0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
e6b0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
e6c0: 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d tent "powersafe-
e6d0: 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 overwrite" or "P
e6e0: 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 SOW" setting. T
e6f0: 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a he PSOW setting.
e700: 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 ** determines th
e710: 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f e [SQLITE_IOCAP_
e720: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
e730: 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a ITE] bit of the.
e740: 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 ** xDeviceCharac
e750: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
e760: 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 s. The fourth pa
e770: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
e780: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
e790: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
e7a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
e7b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
e7c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
e7d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
e7e0: 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 o disable zero-d
e7f0: 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 amage mode or 1
e800: 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 to enable zero-d
e810: 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 amage.** mode.
e820: 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 If the integer i
e830: 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 s -1, then it is
e840: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
e850: 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a h the current.**
e860: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
e870: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
e880: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e890: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a NTL_OVERWRITE]].
e8a0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
e8b0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
e8c0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b opcode is invok
e8d0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 ed by SQLite aft
e8e0: 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 er opening.** a
e8f0: 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f write transactio
e900: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 n to indicate th
e910: 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 at, unless it is
e920: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 rolled back for
e930: 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c some.** reason,
e940: 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 the entire data
e950: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 base file will b
e960: 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 e overwritten by
e970: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a the current .**
e980: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
e990: 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 is is used by VA
e9a0: 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e CUUM operations.
e9b0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
e9c0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
e9d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
e9e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
e9f0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 E] opcode can be
ea00: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
ea10: 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 the names of.**
ea20: 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 all [VFSes] in t
ea30: 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 he VFS stack. T
ea40: 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 he names are of
ea50: 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e all VFS shims an
ea60: 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 d the.** final b
ea70: 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 ottom-level VFS
ea80: 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f are written into
ea90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
eaa0: 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
eab0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
eac0: 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 the result is s
ead0: 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 tored in the cha
eae0: 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 r* variable.** t
eaf0: 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 hat the fourth p
eb00: 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c arameter of [sql
eb10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
eb20: 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a l()] points to..
eb30: 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 ** The caller is
eb40: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
eb50: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d freeing the mem
eb60: 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 ory when done.
eb70: 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 As with.** all f
eb80: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 ile-control acti
eb90: 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f ons, there is no
eba0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
ebb0: 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c this will actual
ebc0: 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e ly.** do anythin
ebd0: 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 g. Callers shou
ebe0: 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 ld initialize th
ebf0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 e char* variable
ec00: 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f to a NULL.** po
ec10: 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 inter in case th
ec20: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 is file-control
ec30: 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 is not implement
ec40: 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 ed. This file-c
ec50: 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 ontrol.** is int
ec60: 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f ended for diagno
ec70: 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a stic use only..*
ec80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ec90: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d E_FCNTL_PRAGMA]]
eca0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 .** ^Whenever a
ecb0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
ecc0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e nt is parsed, an
ecd0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
ece0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 RAGMA] .** file
ecf0: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 control is sent
ed00: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c to the open [sql
ed10: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
ed20: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a t corresponding.
ed30: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ** to the databa
ed40: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 se file to which
ed50: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 the pragma stat
ed60: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 ement refers. ^T
ed70: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 he argument.** t
ed80: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 o the [SQLITE_FC
ed90: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
eda0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 control is an a
edb0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 rray of.** point
edc0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 ers to strings (
edd0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 char**) in which
ede0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d the second elem
edf0: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 ent of the array
ee00: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
ee10: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e of the pragma an
ee20: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d d the third elem
ee30: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ent is the argum
ee40: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 ent to the.** pr
ee50: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 agma or NULL if
ee60: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e the pragma has n
ee70: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 o argument. ^Th
ee80: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e e handler for an
ee90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
eea0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
eeb0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f ontrol can optio
eec0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 nally make the f
eed0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 irst element.**
eee0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 of the char** ar
eef0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 gument point to
ef00: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 a string obtaine
ef10: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
ef20: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 mprintf()].** or
ef30: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
ef40: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 and that string
ef50: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 will become the
ef60: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 result of the pr
ef70: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 agma or.** the e
ef80: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 rror message if
ef90: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 the pragma fails
efa0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 . ^If the.** [SQ
efb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
efc0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
efd0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
efe0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 NOTFOUND], then
eff0: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 normal .** [PRAG
f000: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 MA] processing c
f010: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 ontinues. ^If t
f020: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
f030: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 _PRAGMA].** file
f040: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
f050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
f060: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 en the parser as
f070: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
f080: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 * VFS has handle
f090: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 d the PRAGMA its
f0a0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 elf and the pars
f0b0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e er generates a n
f0c0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 o-op.** prepared
f0d0: 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 statement. ^If
f0e0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
f0f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
f100: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a control returns.
f110: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f ** any result co
f120: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 de other than [S
f130: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 QLITE_OK] or [SQ
f140: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 LITE_NOTFOUND],
f150: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 that means.** th
f160: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 at the VFS encou
f170: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 ntered an error
f180: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 while handling t
f190: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 he [PRAGMA] and
f1a0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 the.** compilati
f1b0: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 on of the PRAGMA
f1c0: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 fails with an e
f1d0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c rror. ^The [SQL
f1e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
f1f0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
f200: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 l occurs at the
f210: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 beginning of pra
f220: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e gma statement an
f230: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a alysis and so.**
f240: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f it is able to o
f250: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e verride built-in
f260: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
f270: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ents..**.** <li>
f280: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [[SQLITE_FCNTL_B
f290: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 USYHANDLER]].**
f2a0: 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 ^This file-contr
f2b0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ol may be invoke
f2c0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 d by SQLite on t
f2d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
f2e0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 handle.** short
f2f0: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f ly after it is o
f300: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 pened in order t
f310: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 o provide a cust
f320: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 om VFS with acce
f330: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e ss.** to the con
f340: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 nections busy-ha
f350: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 ndler callback.
f360: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
f370: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a of type (void **
f380: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 ).** - an array
f390: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 of two (void *)
f3a0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 values. The firs
f3b0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 t (void *) actua
f3c0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f lly points.** to
f3d0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
f3e0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 ype (int (*)(voi
f3f0: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 d *)). In order
f400: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f to invoke the co
f410: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 nnections.** bus
f420: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 y-handler, this
f430: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
f440: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
f450: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 the second (void
f460: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 *) in.** the ar
f470: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ray as the only
f480: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 argument. If it
f490: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
f4a0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 , then the opera
f4b0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
f4c0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 e retried. If it
f4d0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
f4e0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 he custom VFS sh
f4f0: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 ould abandon the
f500: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 .** current oper
f510: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
f520: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
f530: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a TEMPFILENAME]].*
f540: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 * ^Application c
f550: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 66 an invoke this f
f560: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 68 ile-control to h
f570: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 ave SQLite gener
f580: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 ate a.** tempora
f590: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e ry filename usin
f5a0: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
f5b0: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c ithm that is fol
f5c0: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 lowed to generat
f5d0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 e.** temporary f
f5e0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d ilenames for TEM
f5f0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 P tables and oth
f600: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 er internal uses
f610: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 . The.** argume
f620: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 nt should be a c
f630: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c har** which will
f640: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 be filled with
f650: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 the filename.**
f660: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
f670: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
f680: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
f690: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 c()]. The calle
f6a0: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f r should.** invo
f6b0: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ke [sqlite3_free
f6c0: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c ()] on the resul
f6d0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d t to avoid a mem
f6e0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 ory leak..**.**
f6f0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </ul>.*/.#define
f700: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f SQLITE_FCNTL_LO
f710: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 CKSTATE
f720: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
f730: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
f740: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 ROXYFILE
f750: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
f760: 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 QLITE_SET_LOCKPR
f770: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 OXYFILE
f780: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
f790: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 LITE_LAST_ERRNO
f7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
f7b0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
f7c0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
f7d0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 INT
f7e0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
f7f0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
f800: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 IZE
f810: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
f820: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
f830: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 NTER
f840: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
f850: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 _FCNTL_SYNC_OMIT
f860: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 TED 8
f870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f880: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
f890: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a ETRY 9.
f8a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
f8b0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
f8c0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
f8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
f8e0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 NTL_OVERWRITE
f8f0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 11.#d
f900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
f910: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 TL_VFSNAME
f920: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 12.#de
f930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
f940: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
f950: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 WRITE 13.#def
f960: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
f970: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
f980: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 14.#defi
f990: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
f9a0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 BUSYHANDLER
f9b0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 15.#defin
f9c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 e SQLITE_FCNTL_T
f9d0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 EMPFILENAME
f9e0: 20 20 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 16../*.**
f9f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
fa00: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 Handle.**.** The
fa10: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
fa20: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
fa30: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
fa40: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
fa50: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
fa60: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
fa70: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
fa80: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
fa90: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
faa0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
fab0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
fac0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
fad0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
fae0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
faf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
fb00: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
fb10: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
fb20: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
fb30: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
fb40: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
fb50: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
fb60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
fb70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
fb80: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a OS Interface Obj
fb90: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ect.**.** An ins
fba0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c tance of the sql
fbb0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
fbc0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
fbd0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a rface between.**
fbe0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
fbf0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
fc00: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
fc10: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
fc20: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
fc30: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
fc40: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
fc50: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 l file system".
fc60: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 See.** the [VFS
fc70: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 | VFS documenta
fc80: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 tion] for furthe
fc90: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a r information..*
fca0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f *.** The value o
fcb0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 f the iVersion f
fcc0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c ield is initiall
fcd0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c y 1 but may be l
fce0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 arger in.** futu
fcf0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
fd00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e QLite. Addition
fd10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 al fields may be
fd20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 appended to thi
fd30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e s.** object when
fd40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
fd50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 lue is increased
fd60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 . Note that the
fd70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 structure.** of
fd80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
fd90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 object changes
fda0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 in the transacti
fdb0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 on between.** SQ
fdc0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
fdd0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 .9 and 3.6.0 and
fde0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
fdf0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a n field was not.
fe00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a ** modified..**.
fe10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 ** The szOsFile
fe20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a field is the siz
fe30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 e of the subclas
fe40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c sed [sqlite3_fil
fe50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 e].** structure
fe60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 used by this VFS
fe70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 . mxPathname is
fe80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e the maximum len
fe90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 gth of.** a path
fea0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 name in this VFS
feb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
fec0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f ed sqlite3_vfs o
fed0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 bjects are kept
fee0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 on a linked list
fef0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 formed by.** th
ff00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
ff10: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 The [sqlite3_v
ff20: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a fs_register()].*
ff30: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 * and [sqlite3_v
ff40: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d fs_unregister()]
ff50: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 interfaces mana
ff60: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 ge this list.**
ff70: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 in a thread-safe
ff80: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 way. The [sqli
ff90: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 te3_vfs_find()]
ffa0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 interface.** sea
ffb0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 rches the list.
ffc0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 Neither the app
ffd0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f lication code no
ffe0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 r the VFS.** imp
fff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
10000 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 ld use the pNext
10010 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
10020 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 The pNext field
10030 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c is the only fiel
10040 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 d in the sqlite3
10050 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 _vfs.** structur
10060 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 e that SQLite wi
10070 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 ll ever modify.
10080 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c SQLite will onl
10090 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d y access.** or m
100a0 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 odify this field
100b0 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 while holding a
100c0 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 particular stat
100d0 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 ic mutex..** The
100e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
100f0 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 uld never modify
10100 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e anything within
10110 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
10120 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 .** object once
10130 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 the object has b
10140 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a een registered..
10150 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 **.** The zName
10160 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 field holds the
10170 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 name of the VFS
10180 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d module. The nam
10190 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 e must.** be uni
101a0 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 que across all V
101b0 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a FS modules..**.*
101c0 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
101d0 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 xOpen]].** ^SQLi
101e0 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
101f0 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 at the zFilename
10200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
10210 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 pen.** is either
10220 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
10230 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e or string obtain
10240 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c ed.** from xFull
10250 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 Pathname() with
10260 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 an optional suff
10270 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 ix added..** ^If
10280 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 a suffix is add
10290 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e ed to the zFilen
102a0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 ame parameter, i
102b0 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 t will.** consis
102c0 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d t of a single "-
102d0 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c " character foll
102e0 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 owed by no more
102f0 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 than.** 11 alpha
10300 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 numeric and/or "
10310 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -" characters..*
10320 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 * ^SQLite furthe
10330 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 r guarantees tha
10340 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 t.** the string
10350 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e will be valid an
10360 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 d unchanged unti
10370 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a l xClose() is.**
10380 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 called. Because
10390 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 of the previous
103a0 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 sentence,.** th
103b0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
103c0 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 can safely stor
103d0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 e a pointer to t
103e0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 he.** filename i
103f0 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 f it needs to re
10400 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e member the filen
10410 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ame for some rea
10420 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a son..** If the z
10430 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
10440 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 er to xOpen is a
10450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
10460 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 en xOpen.** must
10470 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 invent its own
10480 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 temporary name f
10490 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 or the file. ^W
104a0 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 henever the .**
104b0 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 xFilename parame
104c0 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 ter is NULL it w
104d0 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 ill also be the
104e0 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a case that the.**
104f0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
10500 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 will include [S
10510 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
10520 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a EONCLOSE]..**.**
10530 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
10540 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
10550 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
10560 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
10570 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
10580 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
10590 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
105a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
105b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
105c0 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
105d0 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
105e0 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
105f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
10600 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
10610 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
10620 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f .** If xOpen() o
10630 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 pens a file read
10640 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 -only then it se
10650 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f ts *pOutFlags to
10660 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c .** include [SQL
10670 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
10680 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 Y]. Other bits
10690 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 in *pOutFlags ma
106a0 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 y be set..**.**
106b0 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^(SQLite will al
106c0 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 so add one of th
106d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 e following flag
106e0 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 s to the xOpen()
106f0 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 .** call, depend
10700 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 ing on the objec
10710 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a t being opened:.
10720 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
10730 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
10740 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _MAIN_DB].** <li
10750 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
10760 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a MAIN_JOURNAL].**
10770 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
10780 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 PEN_TEMP_DB].**
10790 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
107a0 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d EN_TEMP_JOURNAL]
107b0 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
107c0 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
107d0 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
107e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
107f0 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
10800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 [SQLITE_OPEN_MAS
10810 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 TER_JOURNAL].**
10820 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
10830 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e EN_WAL].** </ul>
10840 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c )^.**.** The fil
10850 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 e I/O implementa
10860 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 tion can use the
10870 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 object type fla
10880 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 gs to.** change
10890 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
108a0 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
108b0 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
108c0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
108d0 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
108e0 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
108f0 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
10900 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 might make.** t
10910 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 he open of a jou
10920 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f rnal file a no-o
10930 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 p. Writes to th
10940 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 is journal would
10950 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f .** also be no-o
10960 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 ps, and any atte
10970 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 mpt to read the
10980 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 journal would re
10990 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 turn.** SQLITE_I
109a0 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
109b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
109c0 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
109d0 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 t a database.**
109e0 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 file will be doi
109f0 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 ng page-aligned
10a00 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 sector reads and
10a10 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e writes in a ran
10a20 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 dom.** order and
10a30 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 set up its I/O
10a40 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 subsystem accord
10a50 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ingly..**.** SQL
10a60 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 ite might also a
10a70 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
10a80 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
10a90 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
10aa0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
10ab0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
10ac0 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
10ad0 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
10ae0 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
10af0 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
10b00 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 The [SQLITE_OPE
10b10 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
10b20 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
10b30 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a file should be.*
10b40 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 * deleted when i
10b50 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 t is closed. ^T
10b60 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
10b70 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
10b80 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f * will be set fo
10b90 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 r TEMP databases
10ba0 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e and their journ
10bb0 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a als, transient.*
10bc0 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 * databases, and
10bd0 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a subjournals..**
10be0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
10bf0 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
10c00 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 flag is always
10c10 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 used in conjunct
10c20 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ion.** with the
10c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
10c40 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 ATE] flag, which
10c50 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 are both direct
10c60 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 ly.** analogous
10c70 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e to the O_EXCL an
10c80 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 d O_CREAT flags
10c90 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 of the POSIX ope
10ca0 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 n().** API. The
10cb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 SQLITE_OPEN_EXC
10cc0 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 LUSIVE flag, whe
10cd0 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 n paired with th
10ce0 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 e .** SQLITE_OPE
10cf0 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 N_CREATE, is use
10d00 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
10d10 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 at file should a
10d20 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 lways.** be crea
10d30 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 ted, and that it
10d40 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 is an error if
10d50 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 it already exist
10d60 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e s..** It is <i>n
10d70 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 ot</i> used to i
10d80 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 ndicate the file
10d90 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 should be opene
10da0 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 d .** for exclus
10db0 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a ive access..**.*
10dc0 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 * ^At least szOs
10dd0 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 File bytes of me
10de0 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 mory are allocat
10df0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
10e00 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 to hold the [sq
10e10 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 lite3_file] stru
10e20 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 cture passed as
10e30 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 the third.** arg
10e40 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 ument to xOpen.
10e50 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f The xOpen metho
10e60 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 d does not have
10e70 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 to.** allocate t
10e80 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 he structure; it
10e90 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c should just fil
10ea0 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 l it in. Note t
10eb0 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e hat.** the xOpen
10ec0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 method must set
10ed0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
10ee0 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 e.pMethods to ei
10ef0 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 ther.** a valid
10f00 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
10f10 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 ods] object or t
10f20 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d o NULL. xOpen m
10f30 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 ust do.** this e
10f40 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 ven if the open
10f50 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 fails. SQLite e
10f60 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 xpects that the
10f70 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
10f80 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 thods.** element
10f90 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
10fa0 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 fter xOpen retur
10fb0 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ns regardless of
10fc0 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 the success.**
10fd0 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 or failure of th
10fe0 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a e xOpen call..**
10ff0 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 .** [[sqlite3_vf
11000 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e s.xAccess]].** ^
11010 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
11020 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
11030 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
11040 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
11050 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
11060 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
11070 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
11080 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
11090 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
110a0 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
110b0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
110c0 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
110d0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
110e0 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
110f0 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
11100 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
11110 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 The file can be
11120 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a.** directory.
11130 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 .**.** ^SQLite w
11140 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
11150 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
11160 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 athname+1 bytes
11170 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 for the.** outpu
11180 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 t buffer xFullPa
11190 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 thname. The exa
111a0 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f ct size of the o
111b0 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
111c0 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 is also passed a
111d0 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f s a parameter to
111e0 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 both methods.
111f0 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 If the output bu
11200 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c ffer.** is not l
11210 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 arge enough, [SQ
11220 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 LITE_CANTOPEN] s
11230 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
11240 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 d. Since this is
11250 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 .** handled as a
11260 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
11270 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c SQLite, vfs impl
11280 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 ementations shou
11290 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 ld endeavor.** t
112a0 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
112b0 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 y setting mxPath
112c0 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 name to a suffic
112d0 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c iently large val
112e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 ue..**.** The xR
112f0 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c andomness(), xSl
11300 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 eep(), xCurrentT
11310 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 ime(), and xCurr
11320 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a entTimeInt64().*
11330 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 * interfaces are
11340 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
11350 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
11360 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
11370 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
11380 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
11390 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
113a0 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
113b0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
113c0 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
113d0 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
113e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
113f0 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
11400 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
11410 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
11420 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
11430 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
11440 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
11450 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 obtained..** The
11460 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
11470 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
11480 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
11490 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
114a0 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
114b0 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
114c0 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 iven. ^The xCur
114d0 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 rentTime().** me
114e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a thod returns a J
114f0 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 ulian Day Number
11500 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 for the current
11510 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 date and time a
11520 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 s.** a floating
11530 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 point value..**
11540 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
11550 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
11560 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 returns, as an i
11570 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 nteger, the Juli
11580 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 an.** Day Number
11590 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 multiplied by 8
115a0 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 6400000 (the num
115b0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ber of milliseco
115c0 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d nds in .** a 24-
115d0 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 hour day). .**
115e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
115f0 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d the xCurrentTim
11600 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 eInt64() method
11610 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 to get the curre
11620 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 nt.** date and t
11630 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 ime if that meth
11640 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 od is available
11650 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 (if iVersion is
11660 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 2 or .** greater
11670 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f and the functio
11680 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
11690 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 NULL) and will
116a0 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 fall back.** to
116b0 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
116c0 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e f xCurrentTimeIn
116d0 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c t64() is unavail
116e0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
116f0 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xSetSystemCall(
11700 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c ), xGetSystemCal
11710 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 l(), and xNestSy
11720 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 stemCall() inter
11730 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 faces.** are not
11740 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c used by the SQL
11750 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 ite core. These
11760 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 optional interf
11770 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 aces are provide
11780 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 d.** by some VFS
11790 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 es to facilitate
117a0 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 testing of the
117b0 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 VFS code. By ove
117c0 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 rriding .** syst
117d0 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 em calls with fu
117e0 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 nctions under it
117f0 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 s control, a tes
11800 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a t program can.**
11810 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 simulate faults
11820 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 and error condi
11830 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 tions that would
11840 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 otherwise be di
11850 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d fficult.** or im
11860 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 possible to indu
11870 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 ce. The set of
11880 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 system calls tha
11890 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 t can be overrid
118a0 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 den.** varies fr
118b0 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e om one VFS to an
118c0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 other, and from
118d0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 one version of t
118e0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 he same VFS to t
118f0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 he.** next. App
11900 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 lications that u
11910 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 se these interfa
11920 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 ces must be prep
11930 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 ared for any.**
11940 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 or all of these
11950 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 interfaces to be
11960 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 NULL or for the
11970 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 ir behavior to c
11980 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e hange.** from on
11990 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
119a0 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 next. Applicat
119b0 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 ions must not at
119c0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a tempt to access.
119d0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 ** any of these
119e0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 methods if the i
119f0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 Version of the V
11a00 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 FS is less than
11a10 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 3..*/.typedef st
11a20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
11a30 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 sqlite3_vfs;.ty
11a40 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
11a50 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
11a60 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 )(void);.struct
11a70 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 sqlite3_vfs {.
11a80 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 int iVersion;
11a90 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 /* Stru
11aa0 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 cture version nu
11ab0 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 mber (currently
11ac0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 3) */. int szOs
11ad0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 File;
11ae0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 /* Size of subc
11af0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 lassed sqlite3_f
11b00 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 ile */. int mxP
11b10 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 athname;
11b20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c /* Maximum fil
11b30 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 e pathname lengt
11b40 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 h */. sqlite3_v
11b50 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 fs *pNext;
11b60 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 /* Next register
11b70 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 ed VFS */. cons
11b80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 t char *zName;
11b90 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
11ba0 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c this virtual fil
11bb0 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f e system */. vo
11bc0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
11bd0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 /* Pointe
11be0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e r to application
11bf0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a -specific data *
11c00 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 /. int (*xOpen)
11c10 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
11c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
11c30 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
11c40 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
11c50 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
11c60 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
11c70 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c t (*xDelete)(sql
11c80 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
11c90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
11ca0 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e t syncDir);. in
11cb0 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c t (*xAccess)(sql
11cc0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
11cd0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
11ce0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 t flags, int *pR
11cf0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
11d00 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 xFullPathname)(s
11d10 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
11d20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
11d30 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a int nOut, char *
11d40 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 zOut);. void *(
11d50 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 *xDlOpen)(sqlite
11d60 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
11d70 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a ar *zFilename);.
11d80 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f void (*xDlErro
11d90 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
11da0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
11db0 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f *zErrMsg);. vo
11dc0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 id (*(*xDlSym)(s
11dd0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 qlite3_vfs*,void
11de0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
11df0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a Symbol))(void);.
11e00 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
11e10 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
11e20 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 void*);. int (
11e30 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 *xRandomness)(sq
11e40 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
11e50 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 nByte, char *zOu
11e60 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 t);. int (*xSle
11e70 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ep)(sqlite3_vfs*
11e80 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e , int microsecon
11e90 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 ds);. int (*xCu
11ea0 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 rrentTime)(sqlit
11eb0 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a e3_vfs*, double*
11ec0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c );. int (*xGetL
11ed0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 astError)(sqlite
11ee0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 3_vfs*, int, cha
11ef0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 r *);. /*. **
11f00 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
11f10 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
11f20 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 1 of the sqlite
11f30 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a _vfs object. **
11f40 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
11f50 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 ose that follow
11f60 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 are added in ver
11f70 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a sion 2 or later.
11f80 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 */. int (*xCu
11f90 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 rrentTimeInt64)(
11fa0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 sqlite3_vfs*, sq
11fb0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 lite3_int64*);.
11fc0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
11fd0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
11fe0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 n versions 1 and
11ff0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 2 of the sqlite
12000 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
12010 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 * Those below ar
12020 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 e for version 3
12030 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a and greater.. *
12040 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 /. int (*xSetSy
12050 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
12060 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
12070 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
12080 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b e3_syscall_ptr);
12090 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 . sqlite3_sysca
120a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 ll_ptr (*xGetSys
120b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
120c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
120d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e r *zName);. con
120e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 st char *(*xNext
120f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
12100 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
12110 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
12120 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
12130 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
12140 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f versions 1 thro
12150 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c ugh 3 of the sql
12160 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
12170 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 ** New fields
12180 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
12190 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f in figure versio
121a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ns. The iVersio
121b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c n. ** value wil
121c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e l increment when
121d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e ever this happen
121e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a s. . */.};../*.
121f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
12200 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 gs for the xAcce
12210 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ss VFS method.**
12220 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
12230 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
12240 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
12250 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
12260 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
12270 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
12280 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
12290 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d ct. They determ
122a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
122b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
122c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
122d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
122e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
122f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
12300 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
12310 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
12320 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
12330 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
12340 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
12350 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
12360 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
12370 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
12380 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 her the named di
12390 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 rectory is both
123a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
123b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 table.** (in oth
123c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c er words, if fil
123d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c es can be added,
123e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 removed, and re
123f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 named within.**
12400 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a the directory)..
12410 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 ** The SQLITE_AC
12420 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 CESS_READWRITE c
12430 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 onstant is curre
12440 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 ntly used only b
12450 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 y the.** [temp_s
12460 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
12470 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 ragma], though t
12480 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 his could change
12490 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 in a future.**
124a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
124b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 e..** With SQLIT
124c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 E_ACCESS_READ, t
124d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
124e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
124f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
12500 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 readable. The S
12510 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
12520 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a D constant is.**
12530 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 currently unuse
12540 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 d, though it mig
12550 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 ht be used in a
12560 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
12570 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a f.** SQLite..*/.
12580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
12590 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 CCESS_EXISTS
125a0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
125b0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
125c0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 E 1 /* Used by
125d0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f PRAGMA temp_sto
125e0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a re_directory */.
125f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
12600 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 CCESS_READ
12610 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 2 /* Unused */
12620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12630 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
12640 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 xShmLock VFS met
12650 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
12660 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
12670 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 s define the var
12680 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 ious locking ope
12690 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 rations.** allow
126a0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f ed by the xShmLo
126b0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 ck method of [sq
126c0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
126d0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f ]. The.** follo
126e0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c wing are the onl
126f0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 y legal combinat
12700 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f ions of flags to
12710 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b the.** xShmLock
12720 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
12730 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c ul>.** <li> SQL
12740 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
12750 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
12760 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
12770 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
12780 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
12790 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
127a0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
127b0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
127c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
127d0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
127e0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
127f0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a E.** </ul>.**.**
12800 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c When unlocking,
12810 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 the same SHARED
12820 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c or EXCLUSIVE fl
12830 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c ag must be suppl
12840 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 ied as.** was gi
12850 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 ven no the corre
12860 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 sponding lock.
12870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c .**.** The xShmL
12880 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 ock method can t
12890 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
128a0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 n unlocked and S
128b0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 HARED or.** betw
128c0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 een unlocked and
128d0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 EXCLUSIVE. It
128e0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f cannot transitio
128f0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 n between SHARED
12900 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 .** and EXCLUSIV
12910 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 E..*/.#define SQ
12920 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
12930 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
12940 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
12950 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
12960 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 e SQLITE_SHM_SHA
12970 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 RED 4.#def
12980 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 ine SQLITE_SHM_E
12990 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f XCLUSIVE 8../
129a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
129b0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 aximum xShmLock
129c0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 index.**.** The
129d0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
129e0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d on [sqlite3_io_m
129f0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 ethods] may use
12a00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 values.** betwee
12a10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 n 0 and this upp
12a20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 er bound as its
12a30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e "offset" argumen
12a40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 t..** The SQLite
12a50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 core will never
12a60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 attempt to acqu
12a70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 ire or release a
12a80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 .** lock outside
12a90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a of this range.*
12aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12ab0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 _SHM_NLOCK
12ac0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8.../*.** CAPI
12ad0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 3REF: Initialize
12ae0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
12af0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ary.**.** ^The s
12b00 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
12b10 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
12b20 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
12b30 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
12b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 ^The sqlite3_shu
12b50 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
12b60 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
12b70 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
12b80 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
12b90 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
12ba0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 ialize()..** The
12bb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
12bc0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 designed to aid
12bd0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 in process initi
12be0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a alization and.**
12bf0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 shutdown on emb
12c00 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 edded systems.
12c10 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c Workstation appl
12c20 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a ications using.*
12c30 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c * SQLite normall
12c40 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f y do not need to
12c50 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f invoke either o
12c60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
12c70 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ..**.** A call t
12c80 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
12c90 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 lize() is an "ef
12ca0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
12cb0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 it is.** the fi
12cc0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
12cd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
12ce0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 invoked during
12cf0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a the lifetime of.
12d00 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 ** the process,
12d10 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 or if it is the
12d20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 first time sqlit
12d30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12d40 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f is invoked.** fo
12d50 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 llowing a call t
12d60 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
12d70 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e wn(). ^(Only an
12d80 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a effective call.
12d90 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e ** of sqlite3_in
12da0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 itialize() does
12db0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 any initializati
12dc0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 on. All other c
12dd0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d alls.** are harm
12de0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
12df0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
12e00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12e10 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 ) is an "effecti
12e20 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 ve" call if it i
12e30 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 s the first.** c
12e40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
12e50 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 hutdown() since
12e60 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 the last sqlite3
12e70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 _initialize().
12e80 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 ^(Only.** an eff
12e90 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 ective call to s
12ea0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12eb0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 ) does any deini
12ec0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 tialization..**
12ed0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 All other valid
12ee0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
12ef0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 _shutdown() are
12f00 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e harmless no-ops.
12f10 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )^.**.** The sql
12f20 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12f30 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 ) interface is t
12f40 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 hreadsafe, but s
12f50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12f60 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 ).** is not. Th
12f70 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
12f80 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d wn() interface m
12f90 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ust only be call
12fa0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e ed from a.** sin
12fb0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c gle thread. All
12fc0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 open [database
12fd0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 connections] mus
12fe0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 t be closed and
12ff0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c all.** other SQL
13000 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 ite resources mu
13010 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 st be deallocate
13020 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b d prior to invok
13030 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ing.** sqlite3_s
13040 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a hutdown()..**.**
13050 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 Among other thi
13060 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e ngs, ^sqlite3_in
13070 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 itialize() will
13080 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
13090 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 3_os_init(). Si
130a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 milarly, ^sqlite
130b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 3_shutdown().**
130c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 will invoke sqli
130d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a te3_os_end()..**
130e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
130f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
13100 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
13110 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
13120 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 cess..** ^If for
13130 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 some reason, sq
13140 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
13150 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
13160 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 initialize.** th
13170 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 e library (perha
13180 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 ps it is unable
13190 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 to allocate a ne
131a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 eded resource su
131b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 ch.** as a mutex
131c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ) it returns an
131d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
131e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
131f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 OK]..**.** ^The
13200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
13210 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 ze() routine is
13220 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c called internall
13230 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a y by many other.
13240 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
13250 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 aces so that an
13260 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 application usua
13270 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 lly does not nee
13280 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 d to.** invoke s
13290 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
132a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 e() directly. F
132b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c or example, [sql
132c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
132d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e calls sqlite3_in
132e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 itialize() so th
132f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
13300 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
13310 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 ically.** initia
13320 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 lized when [sqli
13330 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 te3_open()] is c
13340 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 alled if it has
13350 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a not be initializ
13360 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 ed.** already.
13370 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c ^However, if SQL
13380 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
13390 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
133a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a _OMIT_AUTOINIT].
133b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
133c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 option, then the
133d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 automatic calls
133e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 to sqlite3_init
133f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 ialize().** are
13400 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 omitted and the
13410 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
13420 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e call sqlite3_in
13430 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
13440 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 tly.** prior to
13450 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
13460 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
13470 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 . For maximum p
13480 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 ortability,.** i
13490 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
134a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f that applicatio
134b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 ns always invoke
134c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
134d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c ize().** directl
134e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 y prior to using
134f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 any other SQLit
13500 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 e interface. Fu
13510 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a ture releases.**
13520 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 of SQLite may r
13530 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e equire this. In
13540 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
13550 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 e behavior exhib
13560 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c ited.** when SQL
13570 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
13580 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 with [SQLITE_OMI
13590 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 T_AUTOINIT] migh
135a0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 t become the.**
135b0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 default behavior
135c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
135d0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
135e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e..**.** The sql
135f0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 ite3_os_init() r
13600 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 outine does oper
13610 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 ating-system spe
13620 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c cific.** initial
13630 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 ization of the S
13640 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
13650 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 The sqlite3_os_e
13660 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 nd().** routine
13670 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 undoes the effec
13680 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f t of sqlite3_os_
13690 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c init(). Typical
136a0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 tasks.** perfor
136b0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 med by these rou
136c0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c tines include al
136d0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c location or deal
136e0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 location.** of s
136f0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c tatic resources,
13700 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
13710 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 of global variab
13720 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 les,.** setting
13730 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 up a default [sq
13740 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c lite3_vfs] modul
13750 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 e, or setting up
13760 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f .** a default co
13770 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e nfiguration usin
13780 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 g [sqlite3_confi
13790 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 g()]..**.** The
137a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
137b0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 ld never invoke
137c0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f either sqlite3_o
137d0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 s_init().** or s
137e0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
137f0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 directly. The a
13800 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
13810 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a d only invoke.**
13820 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
13830 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ize() and sqlite
13840 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 3_shutdown(). T
13850 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
13860 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 it().** interfac
13870 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f e is called auto
13880 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
13890 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
138a0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ) and.** sqlite3
138b0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c _os_end() is cal
138c0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 led by sqlite3_s
138d0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 hutdown(). Appr
138e0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 opriate.** imple
138f0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 mentations for s
13900 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
13910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
13920 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 end().** are bui
13930 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 lt into SQLite w
13940 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c hen it is compil
13950 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e ed for Unix, Win
13960 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a dows, or OS/2..*
13970 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 * When [custom b
13980 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f uilds | built fo
13990 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d r other platform
139a0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 s].** (using the
139b0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 [SQLITE_OS_OTHE
139c0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d R=1] compile-tim
139d0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 e.** option) the
139e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
139f0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 t supply a suita
13a00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
13a10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 on for.** sqlite
13a20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 3_os_init() and
13a30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
13a40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f . An applicatio
13a50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d n-supplied.** im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
13a70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
13a80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ) or sqlite3_os_
13a90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 end().** must re
13aa0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
13ab0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 on success and
13ac0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f some other [erro
13ad0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 r code] upon.**
13ae0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 failure..*/.SQLI
13af0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
13b00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f e3_initialize(vo
13b10 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
13b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 int sqlite3_shut
13b30 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 down(void);.SQLI
13b40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
13b50 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 e3_os_init(void)
13b60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
13b70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
13b80 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
13b90 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
13ba0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c ing The SQLite L
13bb0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 ibrary.**.** The
13bc0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
13bd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
13be0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 sed to make glob
13bf0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e al configuration
13c00 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 .** changes to S
13c10 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
13c20 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f o tune SQLite to
13c30 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
13c40 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 eds of.** the ap
13c50 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
13c60 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
13c70 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 ation is recomme
13c80 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a nded for most.**
13c90 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e applications an
13ca0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e d so this routin
13cb0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 e is usually not
13cc0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 necessary. It
13cd0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 is.** provided t
13ce0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 o support rare a
13cf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 pplications with
13d00 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a unusual needs..
13d10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
13d20 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
13d30 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 face is not thre
13d40 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 adsafe. The app
13d50 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 lication.** must
13d60 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 insure that no
13d70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
13d80 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f erfaces are invo
13d90 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 ked by other.**
13da0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 threads while sq
13db0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
13dc0 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 s running. Furt
13dd0 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 hermore, sqlite3
13de0 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 _config().** may
13df0 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 only be invoked
13e00 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 prior to librar
13e10 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
13e20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
13e30 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
13e40 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f or after shutdo
13e50 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 wn by [sqlite3_s
13e60 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e hutdown()]..** ^
13e70 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 If sqlite3_confi
13e80 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 g() is called af
13e90 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ter [sqlite3_ini
13ea0 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 tialize()] and b
13eb0 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 efore.** [sqlite
13ec0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 3_shutdown()] th
13ed0 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 en it will retur
13ee0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e n SQLITE_MISUSE.
13ef0 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 .** Note, howeve
13f00 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 r, that ^sqlite3
13f10 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 _config() can be
13f20 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 called as part
13f30 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d of the.** implem
13f40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 entation of an a
13f50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
13f60 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 ed [sqlite3_os_i
13f70 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 nit()]..**.** Th
13f80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
13f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to sqlite3_conf
13fa0 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 ig() is an integ
13fb0 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 er.** [configura
13fc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 tion option] tha
13fd0 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 t determines.**
13fe0 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 what property of
13ff0 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 SQLite is to be
14000 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 configured. Su
14010 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
14020 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e ts.** vary depen
14030 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e ding on the [con
14040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14050 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
14060 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
14070 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 ** ^When a confi
14080 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
14090 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f is set, sqlite3_
140a0 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 config() returns
140b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
140c0 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 ^If the option
140d0 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 is unknown or SQ
140e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 Lite is unable t
140f0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e o set the option
14100 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f .** then this ro
14110 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
14120 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
14130 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 code]..*/.SQLITE
14140 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
14150 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
14160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
14170 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
14180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14190 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
141a0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
141b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
141c0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
141d0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
141e0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
141f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
14200 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
14210 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
14220 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
14230 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
14240 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
14250 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
14260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14270 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
14280 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
14290 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
142a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
142b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
142c0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
142d0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
142e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
142f0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
14300 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
14310 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
14320 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
14330 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
14340 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
14350 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
14360 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
14370 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
14380 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
14390 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
143a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
143b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
143c0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
143d0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
143e0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
143f0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
14400 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
14410 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 successful..*/.S
14420 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
14430 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
14440 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
14450 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
14460 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
14470 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
14480 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
14490 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
144a0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
144b0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
144c0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
144d0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
144e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
144f0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
14500 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
14510 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
14520 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
14530 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
14540 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
14550 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
14560 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
14570 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
14580 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
14590 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
145a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
145b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
145c0 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
145d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
145e0 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
145f0 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
14600 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
14610 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
14620 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
14630 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
14640 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
14650 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
14660 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
14670 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
14680 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
14690 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
146a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
146b0 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
146c0 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
146d0 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
146e0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
146f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
14700 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
14710 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
14720 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
14730 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
14740 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
14750 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
14760 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
14770 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
14780 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
14790 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
147a0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
147b0 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
147c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
147d0 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
147e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
147f0 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
14800 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
14810 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
14820 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
14830 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
14840 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
14850 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
14860 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
14870 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
14880 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
14890 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
148a0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
148b0 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
148c0 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
148d0 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
148e0 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
148f0 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
14900 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
14910 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
14920 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
14930 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
14940 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
14950 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
14960 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
14970 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
14980 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
14990 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
149a0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
149b0 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
149c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
149d0 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
149e0 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
149f0 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
14a00 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
14a10 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
14a20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14a30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
14a40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
14a50 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
14a60 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
14a70 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
14a80 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
14a90 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
14aa0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
14ab0 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
14ac0 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
14ad0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
14ae0 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
14af0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
14b00 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
14b10 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
14b20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
14b30 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
14b40 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
14b50 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
14b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14b70 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
14b80 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
14b90 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
14ba0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
14bb0 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
14bc0 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
14bd0 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
14be0 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
14bf0 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
14c00 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
14c10 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
14c20 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
14c30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
14c40 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
14c50 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
14c60 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
14c70 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
14c80 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
14c90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14ca0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
14cb0 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
14cc0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
14cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
14ce0 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 r. (For example
14cf0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
14d00 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
14d10 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
14d20 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
14d30 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
14d40 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
14d50 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
14d60 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
14d70 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
14d80 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
14d90 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
14da0 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
14db0 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
14dc0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
14dd0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
14de0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
14df0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
14e00 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
14e10 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
14e20 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
14e30 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
14e40 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
14e50 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
14e60 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
14e70 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
14e80 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
14e90 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
14ea0 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
14eb0 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
14ec0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
14ed0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
14ee0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
14ef0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
14f00 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
14f10 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
14f20 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
14f30 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
14f40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
14f50 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
14f60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
14f70 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
14f80 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
14f90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14fa0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
14fb0 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
14fc0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
14fd0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
14fe0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
14ff0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
15000 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
15010 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
15020 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
15030 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
15040 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
15050 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
15060 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
15070 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
15080 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
15090 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
150a0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
150b0 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
150c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
150d0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
150e0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
150f0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
15100 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
15110 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
15120 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
15130 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
15140 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
15150 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
15160 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
15170 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
15180 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
15190 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
151a0 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
151b0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
151c0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
151d0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
151e0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
151f0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
15200 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
15210 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
15220 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
15230 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
15240 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
15250 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
15260 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
15270 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
15280 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
15290 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
152a0 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
152b0 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
152c0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
152d0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
152e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
152f0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
15300 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
15310 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
15320 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
15330 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
15340 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
15350 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
15360 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
15370 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
15380 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
15390 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
153a0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
153b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
153c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
153d0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on}.**.** These
153e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
153f0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
15400 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
15410 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
15420 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
15430 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
15440 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
15450 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
15460 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
15470 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
15480 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
15490 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
154a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
154b0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
154c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
154d0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
154e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
154f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
15500 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
15510 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
15520 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
15530 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
15540 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
15550 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
15560 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15570 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
15580 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
15590 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
155a0 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
155b0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
155c0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
155d0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
155e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
155f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
15600 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
15610 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAD]] <dt>SQLITE
15620 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
15630 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
15640 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
15650 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
15660 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
15670 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
15680 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
15690 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 e] to Single-thr
156a0 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
156b0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
156c0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
156d0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
156e0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
156f0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
15700 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
15710 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
15720 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
15730 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
15740 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
15750 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
15760 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
15770 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
15780 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
15790 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
157a0 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 change the [thre
157b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d ading mode] from
157c0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 its default.**
157d0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d value of Single-
157e0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 thread and so [s
157f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
15800 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a will return .**
15810 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
15820 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
15830 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
15840 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a _SINGLETHREAD.**
15850 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15860 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
15870 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15880 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 G_MULTITHREAD]]
15890 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
158a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 G_MULTITHREAD</d
158b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
158c0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
158d0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
158e0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
158f0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
15900 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d ading mode] to M
15910 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e ulti-thread. In
15920 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
15930 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 disables.** mut
15940 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 exing on [databa
15950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
15960 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
15970 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
15980 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
15990 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ion is responsib
159a0 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 le for serializi
159b0 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 ng access to.**
159c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
159d0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
159e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
159f0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 . But other mut
15a00 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
15a10 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 led so that SQLi
15a20 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 te will be safe
15a30 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 to use in a mult
15a40 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e i-threaded.** en
15a50 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e vironment as lon
15a60 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 g as no two thre
15a70 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ads attempt to u
15a80 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b se the same.** [
15a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
15aa0 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 ion] at the same
15ab0 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 time. ^If SQLi
15ac0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
15ad0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
15ae0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
15af0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
15b00 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
15b10 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
15b20 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
15b30 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d ble to set the M
15b40 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
15b50 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
15b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
15b70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
15b80 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
15b90 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
15ba0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
15bb0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
15bc0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
15bd0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
15be0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15bf0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 IG_SERIALIZED]]
15c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
15c10 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
15c20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
15c30 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
15c40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
15c50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
15c60 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
15c70 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
15c80 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
15c90 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
15ca0 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
15cb0 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
15cc0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
15cd0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
15ce0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
15cf0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
15d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
15d10 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
15d20 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
15d30 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
15d40 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
15d50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
15d60 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
15d70 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
15d80 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
15d90 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
15da0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
15db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15dc0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
15dd0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
15de0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
15df0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
15e00 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
15e10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
15e20 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
15e30 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
15e40 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
15e50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
15e60 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
15e70 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
15e80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
15e90 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
15ea0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
15eb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
15ec0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
15ed0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
15ee0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
15ef0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
15f00 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
15f10 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
15f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15f30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
15f40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
15f50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
15f60 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
15f70 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
15f80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
15f90 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
15fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
15fb0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
15fc0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
15fd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
15fe0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
15ff0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
16000 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
16010 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
16020 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
16030 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
16040 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
16050 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
16060 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 ecifies.** alter
16070 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
16080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16090 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 on routines to b
160a0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 e used in place
160b0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 of.** the memory
160c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
160d0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 ines built into
160e0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 SQLite.)^ ^SQLit
160f0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f e makes.** its o
16100 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
16110 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f of the content o
16120 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
16130 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
16140 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 cture.** before
16150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
16160 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 fig()] call retu
16170 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 rns.</dd>.**.**
16180 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16190 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e GETMALLOC]] <dt>
161a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
161b0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 TMALLOC</dt>.**
161c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
161d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
161e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
161f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
16200 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
16210 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
16220 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
16230 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 ucture. The [sq
16240 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
16250 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
16260 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
16270 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
16280 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
16290 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
162a0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
162b0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
162c0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
162d0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
162e0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
162f0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
16300 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 er that simulati
16310 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ons memory alloc
16320 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 ation failure or
16330 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 .** tracks memor
16340 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 y usage, for exa
16350 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a mple. </dd>.**.*
16360 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
16370 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 G_MEMSTATUS]] <d
16380 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16390 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
163a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
163b0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 ion takes single
163c0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
163d0 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 e int, interpret
163e0 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c ed as a .** bool
163f0 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c ean, which enabl
16400 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
16410 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 he collection of
16420 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16430 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 on .** statistic
16440 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
16450 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
16460 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
16470 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c led, the .** fol
16480 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
16490 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
164a0 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
164b0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
164c0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
164d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
164e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
164f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
16500 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
16510 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
16520 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
16530 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
16540 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f tatus()].** </
16550 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 ul>)^.** ^Memory
16560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
16570 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c istics are enabl
16580 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e ed by default un
16590 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a less SQLite is.*
165a0 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
165b0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f [SQLITE_DEFAULT_
165c0 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 MEMSTATUS]=0 in
165d0 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 which case memor
165e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 y.** allocation
165f0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 statistics are d
16600 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
16610 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a lt..** </dd>.**.
16620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16630 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 IG_SCRATCH]] <dt
16640 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
16650 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c CRATCH</dt>.** <
16660 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
16670 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
16680 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
16690 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 r that SQLite ca
166a0 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 n use for.** scr
166b0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 atch memory. Th
166c0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
166d0 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e guments: A poin
166e0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a ter an 8-byte.**
166f0 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
16700 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 buffer from whic
16710 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c h the scratch al
16720 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 locations will b
16730 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 e.** drawn, the
16740 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
16750 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 atch allocation
16760 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 (sz),.** and the
16770 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
16780 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 of scratch alloc
16790 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 ations (N). The
167a0 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 sz.** argument
167b0 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 must be a multip
167c0 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 le of 16..** The
167d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
167e0 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 must be a pointe
167f0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 r to an 8-byte a
16800 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a ligned buffer.**
16810 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
16820 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
16830 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
16840 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 ll use no more t
16850 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 han two scratch
16860 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
16870 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f ad. So.** N sho
16880 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 uld be set to tw
16890 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 ice the expected
168a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
168b0 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e of threads..** ^
168c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
168d0 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 r require a scra
168e0 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 tch buffer that
168f0 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a is more than 6.*
16900 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 * times the data
16910 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 base page size.
16920 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 ^If SQLite needs
16930 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 needs additiona
16940 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d l.** scratch mem
16950 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 ory beyond what
16960 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 is provided by t
16970 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
16980 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a n option, then .
16990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
169a0 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 oc()] will be us
169b0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 ed to obtain the
169c0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c memory needed.<
169d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
169e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
169f0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
16a00 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
16a10 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
16a20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
16a30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
16a40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
16a50 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
16a60 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 e for.** the dat
16a70 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 abase page cache
16a80 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c with the defaul
16a90 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 t page cache imp
16aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a lementation. .*
16ab0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 * This configura
16ac0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 tion should not
16ad0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 be used if an ap
16ae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
16af0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
16b00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
16b10 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
16b20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16b30 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a PCACHE2 option..
16b40 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
16b50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
16b60 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 this option: A p
16b70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 ointer to 8-byte
16b80 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f aligned.** memo
16b90 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ry, the size of
16ba0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 each page buffer
16bb0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e (sz), and the n
16bc0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 umber of pages (
16bd0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
16be0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
16bf0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
16c00 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
16c10 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 e page.** (a pow
16c20 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 er of two betwee
16c30 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 n 512 and 32768)
16c40 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 plus a little e
16c50 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a xtra for each.**
16c60 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e page header. ^
16c70 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 The page header
16c80 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 size is 20 to 40
16c90 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 bytes depending
16ca0 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 on.** the host
16cb0 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e architecture. ^
16cc0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
16cd0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
16ce0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
16cf0 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 to make sz a li
16d00 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 ttle too large.
16d10 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
16d20 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
16d30 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 int to an alloca
16d40 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 tion of at least
16d50 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
16d60 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 emory..** ^SQLit
16d70 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d e will use the m
16d80 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 emory provided b
16d90 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 y the first argu
16da0 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 ment to satisfy
16db0 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 its.** memory ne
16dc0 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 eds for the firs
16dd0 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 t N pages that i
16de0 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e t adds to cache.
16df0 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c ^If additional
16e00 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
16e10 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
16e20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
16e30 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
16e40 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 option, then.**
16e50 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b SQLite goes to [
16e60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16e70 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 ] for the additi
16e80 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 onal storage spa
16e90 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 ce..** The point
16ea0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
16eb0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a argument must.**
16ec0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
16ed0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 n 8-byte boundar
16ee0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
16ef0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
16f00 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e te.** will be un
16f10 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
16f20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16f30 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 FIG_HEAP]] <dt>S
16f40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
16f50 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
16f60 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
16f70 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
16f80 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
16f90 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
16fa0 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 e.** for all of
16fb0 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
16fc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
16fd0 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 eds beyond those
16fe0 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
16ff0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
17000 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
17010 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
17020 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
17030 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
17040 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 guments: An 8-by
17050 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
17060 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
17070 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
17080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
17090 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
170a0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
170b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
170c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
170d0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
170e0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
170f0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
17100 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
17110 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
17120 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
17130 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
17140 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
17150 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
17160 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
17170 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
17190 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
171a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
171b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
171c0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
171d0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
171e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 r.** [SQLITE_ENA
171f0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 BLE_MEMSYS5] are
17200 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 defined, then t
17210 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d he alternative m
17220 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
17230 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f or is engaged to
17240 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 handle all of S
17250 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c QLites memory al
17260 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a location needs..
17270 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 ** The first poi
17280 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
17290 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 pointer) must b
172a0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
172b0 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 8-byte.** bounda
172c0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
172d0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
172e0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 ite will be unde
172f0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 fined..** The mi
17300 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
17310 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 size is capped
17320 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e at 2**12. Reason
17330 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 able values.** f
17340 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 or the minimum a
17350 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 llocation size a
17360 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 re 2**5 through
17370 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 2**8.</dd>.**.**
17380 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
17390 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c _MUTEX]] <dt>SQL
173a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
173b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
173c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
173d0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
173e0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
173f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
17400 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
17410 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
17420 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
17430 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 e. The argument
17440 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
17450 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
17460 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e vel mutex routin
17470 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
17480 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 place.** the mu
17490 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 tex routines bui
174a0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 lt into SQLite.)
174b0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ^ ^SQLite makes
174c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
174d0 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 * content of the
174e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
174f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
17500 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 re before the ca
17510 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
17520 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 3_config()] retu
17530 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 rns. ^If SQLite
17540 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
17550 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
17560 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
17570 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
17580 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
17590 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
175a0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
175b0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
175c0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
175d0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
175e0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
175f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
17600 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
17610 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 ONFIG_MUTEX conf
17620 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
17630 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
17640 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
17650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
17660 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
17670 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 TEX]] <dt>SQLITE
17680 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
17690 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
176a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
176b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
176c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
176d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
176e0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
176f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
17700 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
17710 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 e. The.** [sqli
17720 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
17730 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
17740 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
17750 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
17760 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 ined mutex routi
17770 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
17780 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
17790 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
177a0 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
177b0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
177c0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
177d0 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 apper used to tr
177e0 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 ack mutex usage
177f0 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a for performance.
17800 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 ** profiling or
17810 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 testing, for exa
17820 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 mple. ^If SQLi
17830 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
17840 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
17850 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
17860 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
17870 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
17880 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
17890 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
178a0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
178b0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
178c0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
178d0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
178e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
178f0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
17900 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
17910 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 X configuration
17920 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 option will.** r
17930 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
17940 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ROR].</dd>.**.**
17950 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
17960 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 _LOOKASIDE]] <dt
17970 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
17980 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
17990 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
179a0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
179b0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
179c0 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 ermine the defau
179d0 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c lt.** memory all
179e0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 ocation for the
179f0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
17a00 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 allocator on ea
17a10 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
17a20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
17a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
17a40 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
17a50 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
17a60 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e e buffer slot an
17a70 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 d the second is
17a80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
17a90 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 slots allocated
17aa0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
17ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 e connection.)^
17ac0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^(This option s
17ad0 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 ets the.** <i>de
17ae0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 fault</i> lookas
17af0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 ide size. The [S
17b00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
17b10 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 OOKASIDE].** ver
17b20 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 b to [sqlite3_db
17b30 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 _config()] can b
17b40 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 e used to change
17b50 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a the lookaside.*
17b60 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
17b70 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f on individual co
17b80 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 nnections.)^ </d
17b90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
17ba0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
17bb0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
17bc0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 NFIG_PCACHE2</dt
17bd0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
17be0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
17bf0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
17c00 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
17c10 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c er to.** an [sql
17c20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
17c30 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 ods2] object. T
17c40 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 his object speci
17c50 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 fies the interfa
17c60 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f ce.** to a custo
17c70 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 m page cache imp
17c80 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 lementation.)^
17c90 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 ^SQLite makes a
17ca0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
17cb0 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 bject and uses i
17cc0 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 t for page cache
17cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
17ce0 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ons.</dd>.**.**
17cf0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
17d00 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 GETPCACHE2]] <dt
17d10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
17d20 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a ETPCACHE2</dt>.*
17d30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
17d40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
17d50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
17d60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
17d70 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
17d80 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
17d90 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 2] object. SQLi
17da0 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 te copies of the
17db0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 current.** page
17dc0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
17dd0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 ation into that
17de0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a object.)^ </dd>.
17df0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17e00 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e ONFIG_LOG]] <dt>
17e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
17e20 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e G</dt>.** <dd> ^
17e30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
17e40 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b G_LOG option tak
17e50 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
17e60 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 : a pointer to a
17e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 .** function wit
17e80 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 h a call signatu
17e90 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f re of void(*)(vo
17ea0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
17eb0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 ar*), .** and a
17ec0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e pointer to void.
17ed0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f ^If the functio
17ee0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
17ef0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 NULL, it is.**
17f00 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 invoked by [sqli
17f10 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 te3_log()] to pr
17f20 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 ocess each loggi
17f30 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
17f40 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 he.** function p
17f50 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 ointer is NULL,
17f60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 the [sqlite3_log
17f70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
17f80 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a comes a no-op..*
17f90 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e * ^The void poin
17fa0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 ter that is the
17fb0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
17fc0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
17fd0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 _LOG is.** passe
17fe0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
17ff0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
18000 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
18010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 ion-defined logg
18020 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 er.** function w
18030 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e henever that fun
18040 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
18050 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 . ^The second p
18060 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
18070 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
18080 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 on is a copy of
18090 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
180a0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 ter to the corre
180b0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c sponding.** [sql
180c0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c ite3_log()] call
180d0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 and is intended
180e0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 to be a [result
180f0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 code] or an.**
18100 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
18110 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 code]. ^The th
18120 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ird parameter pa
18130 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 ssed to the logg
18140 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 er is.** log mes
18150 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 sage after forma
18160 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 tting via [sqlit
18170 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a e3_snprintf()]..
18180 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f ** The SQLite lo
18190 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 gging interface
181a0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
181b0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e ; the logger fun
181c0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 ction.** supplie
181d0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
181e0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e tion must not in
181f0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 voke any SQLite
18200 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e interface..** In
18210 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
18220 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 d application, t
18230 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
18240 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
18250 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 function must b
18260 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f e threadsafe. </
18270 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
18280 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 TE_CONFIG_URI]]
18290 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
182a0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 G_URI.** <dd> Th
182b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
182c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
182d0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 t of type int. I
182e0 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e f non-zero, then
182f0 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 .** URI handling
18300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 is globally ena
18310 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 bled. If the par
18320 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 ameter is zero,
18330 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e then URI handlin
18340 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 g.** is globally
18350 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 disabled. If UR
18360 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
18370 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 obally enabled,
18380 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a all filenames.**
18390 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
183a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
183b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
183c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
183d0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 6()] or.** speci
183e0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 fied as part of
183f0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 [ATTACH] command
18400 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
18410 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 d as URIs, regar
18420 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 dless.** of whet
18430 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b her or not the [
18440 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
18450 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
18460 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a n the database.*
18470 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
18480 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 opened. If it is
18490 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c globally disabl
184a0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 ed, filenames ar
184b0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 e.** only interp
184c0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 reted as URIs if
184d0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
184e0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 _URI flag is set
184f0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 when the.** dat
18500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18510 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 is opened. By d
18520 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 efault, URI hand
18530 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
18540 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 .** disabled. Th
18550 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 e default value
18560 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 may be changed b
18570 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 y compiling with
18580 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
18590 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 USE_URI] symbol
185a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b defined..**.** [
185b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 [SQLITE_CONFIG_C
185c0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
185d0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AN]] <dt>SQLITE_
185e0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
185f0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 INDEX_SCAN.** <d
18600 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 d> This option t
18610 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e akes a single in
18620 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 teger argument w
18630 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 hich is interpre
18640 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c ted as.** a bool
18650 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ean in order to
18660 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
18670 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 e the use of cov
18680 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
18690 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 r.** full table
186a0 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 scans in the que
186b0 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 ry optimizer. T
186c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 he default setti
186d0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 ng is determined
186e0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 .** by the [SQLI
186f0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e TE_ALLOW_COVERIN
18700 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f G_INDEX_SCAN] co
18710 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
18720 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a n, or is "on".**
18730 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 if that compile
18740 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
18750 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 omitted..** The
18760 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 ability to disab
18770 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
18780 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
18790 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
187a0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 ans.** is becaus
187b0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 e some incorrect
187c0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 ly coded legacy
187d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 applications mig
187e0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a ht malfunction.*
187f0 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 * malfunction wh
18800 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 en the optimizat
18810 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 ion is enabled.
18820 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 Providing the a
18830 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 bility to.** dis
18840 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a able the optimiz
18850 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 ation allows the
18860 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 older, buggy ap
18870 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 plication code t
18880 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 o work.** withou
18890 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 t change even wi
188a0 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e th newer version
188b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
188c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
188d0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 IG_PCACHE]] [[SQ
188e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
188f0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 CACHE]].** <dt>S
18900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
18910 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 CHE and SQLITE_C
18920 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a ONFIG_GETPCACHE.
18930 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 ** <dd> These op
18940 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 tions are obsole
18950 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f te and should no
18960 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 t be used by new
18970 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 code..** They a
18980 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 re retained for
18990 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
189a0 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 ibility but are
189b0 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c now no-ops..** <
189c0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dl>.**.** [[SQL
189d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
189e0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 G]].** <dt>SQLIT
189f0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a E_CONFIG_SQLLOG.
18a00 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
18a10 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
18a20 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 able if sqlite i
18a30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
18a40 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e the.** SQLITE_EN
18a50 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 2d ABLE_SQLLOG pre-
18a60 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
18a70 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 defined. The fir
18a80 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 st argument shou
18a90 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 ld.** be a point
18aa0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e er to a function
18ab0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 of type void(*)
18ac0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
18ad0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
18ae0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
18af0 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 should be of ty
18b00 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 pe (void*). The
18b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
18b20 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 ked by the libra
18b30 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 ry.** in three s
18b40 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 eparate circumst
18b50 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 ances, identifie
18b60 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 d by the value p
18b70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 assed as the.**
18b80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
18b90 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 . If the fourth
18ba0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 parameter is 0,
18bb0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
18bc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
18bd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
18be0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 cond argument ha
18bf0 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e s just been open
18c00 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 ed. The third ar
18c10 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 gument.** points
18c20 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e to a buffer con
18c30 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 taining the name
18c40 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 of the main dat
18c50 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 abase file. If t
18c60 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
18c70 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 ameter is 1, the
18c80 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
18c90 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 ent that the thi
18ca0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 rd parameter.**
18cb0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 points to has ju
18cc0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 st been executed
18cd0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 . Or, if the fou
18ce0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
18cf0 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 2, then.** the
18d00 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 connection being
18d10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
18d20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
18d30 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e is being closed.
18d40 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 The.** third pa
18d50 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 rameter is passe
18d60 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 d NULL In this c
18d70 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f ase..** </dl>.*/
18d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18d90 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
18da0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
18db0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18dc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
18dd0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
18de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18df0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
18e00 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
18e10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18e20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
18e30 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
18e40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
18e50 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
18e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
18e70 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
18e80 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
18e90 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
18ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
18eb0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
18ec0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
18ed0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
18ee0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18ef0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
18f00 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
18f10 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
18f20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18f30 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
18f40 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
18f50 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
18f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18f70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
18f80 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
18f90 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
18fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
18fb0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
18fc0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
18fd0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18ff0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
19000 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
19010 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
19020 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
19030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
19040 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
19050 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
19060 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
19070 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
19080 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
19090 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
190a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
190b0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
190c0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
190d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
190e0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
190f0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
19100 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
19110 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
19120 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
19130 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
19140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
19150 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
19160 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
19170 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
19180 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
19190 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
191a0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
191b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
191c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
191d0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
191e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
191f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
19200 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
19210 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
19220 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
19230 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
19240 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
19250 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
19260 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 void* */../*.**
19270 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
19280 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f se Connection Co
19290 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
192a0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
192b0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
192c0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
192d0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
192e0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
192f0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
19300 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
19310 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
19320 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
19330 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
19340 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
19350 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
19360 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
19370 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
19380 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
19390 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
193a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
193b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
193c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
193d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
193e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
193f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 from [sqlite3_d
19400 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d b_config()] to m
19410 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
19420 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
19430 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 . ^The [sqlite3
19440 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
19450 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
19460 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
19470 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
19480 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
19490 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
194a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
194b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
194c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
194d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
194e0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
194f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
19500 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
19510 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c three additional
19520 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
19530 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a determine the .*
19540 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d * [lookaside mem
19550 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
19560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
19570 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
19580 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e onnection]..** ^
19590 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
195a0 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 nt (the third pa
195b0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
195c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
195d0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 is a.** pointer
195e0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 to a memory buf
195f0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c fer to use for l
19600 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e ookaside memory.
19610 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
19620 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 rgument after th
19630 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
19640 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 G_LOOKASIDE verb
19650 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 .** may be NULL
19660 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 in which case SQ
19670 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 Lite will alloca
19680 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 te the.** lookas
19690 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c ide buffer itsel
196a0 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 f using [sqlite3
196b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 _malloc()]. ^The
196c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
196d0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
196e0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
196f0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 e buffer slot.
19700 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
19710 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
19720 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
19730 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
19740 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
19750 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
19760 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
19770 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
19780 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
19790 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
197a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 hird arguments.
197b0 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d The buffer.** m
197c0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
197d0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e o an 8-byte boun
197e0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 dary. ^If the s
197f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
19800 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f o.** SQLITE_DBCO
19810 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 NFIG_LOOKASIDE i
19820 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 s not a multiple
19830 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 of 8, it is int
19840 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 ernally.** round
19850 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e ed down to the n
19860 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 ext smaller mult
19870 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 iple of 8. ^(Th
19880 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
19890 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 ry.** configurat
198a0 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 ion for a databa
198b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 se connection ca
198c0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 n only be change
198d0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 d when that.** c
198e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 onnection is not
198f0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 currently using
19900 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
19910 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 y, or in other w
19920 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 ords.** when the
19930 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 "current value"
19940 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
19950 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
19960 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f us](D,[SQLITE_CO
19970 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c NFIG_LOOKASIDE],
19980 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a ...) is zero..**
19990 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
199a0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 change the looka
199b0 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 side memory conf
199c0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c iguration when l
199d0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f ookaside.** memo
199e0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 ry is in use lea
199f0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 ves the configur
19a00 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 ation unchanged
19a10 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 and returns .**
19a20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e [SQLITE_BUSY].)^
19a30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
19a40 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19a50 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e ENABLE_FKEY</dt>
19a60 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
19a70 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
19a80 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
19a90 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 le the enforceme
19aa0 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 nt of.** [foreig
19ab0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 n key constraint
19ac0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c s]. There shoul
19ad0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
19ae0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
19af0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
19b00 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
19b10 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
19b20 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f disable FK enfo
19b30 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 rcement,.** posi
19b40 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 tive to enable F
19b50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 K enforcement or
19b60 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
19b70 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e ve FK enforcemen
19b80 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 t.** unchanged.
19b90 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
19ba0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
19bb0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
19bc0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
19bd0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
19be0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
19bf0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d ther FK enforcem
19c00 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e ent is off or on
19c10 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
19c20 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
19c30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
19c40 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
19c50 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
19c60 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e h case the FK en
19c70 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e forcement settin
19c80 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
19c90 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
19ca0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
19cb0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
19cc0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c RIGGER</dt>.** <
19cd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
19ce0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
19cf0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 le or disable [C
19d00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
19d10 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 triggers]..** Th
19d20 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
19d30 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
19d40 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
19d50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
19d60 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
19d70 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
19d80 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 e triggers,.** p
19d90 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
19da0 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 e triggers or ne
19db0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
19dc0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 the setting unch
19dd0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 anged..** The se
19de0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
19df0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
19e00 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
19e10 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
19e20 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
19e30 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 icate whether tr
19e40 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 iggers are disab
19e50 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
19e60 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
19e70 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
19e80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
19e90 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
19ea0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
19eb0 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 case the trigger
19ec0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
19ed0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
19ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
19ef0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
19f00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
19f10 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 ASIDE 1001
19f20 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 /* void* int i
19f30 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
19f40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
19f50 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 ABLE_FKEY 10
19f60 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 02 /* int int*
19f70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
19f80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
19f90 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 E_TRIGGER 1003
19fa0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
19fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19fc0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
19fd0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 ble Extended Res
19fe0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ult Codes.**.**
19ff0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
1a000 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
1a010 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 es() routine ena
1a020 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
1a030 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the.** [extende
1a040 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
1a050 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 feature of SQLit
1a060 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 e. ^The extended
1a070 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 result.** codes
1a080 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
1a090 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 default for his
1a0a0 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 torical compatib
1a0b0 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ility..*/.SQLITE
1a0c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1a0d0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
1a0e0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
1a0f0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
1a100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
1a110 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
1a120 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
1a130 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 y in an SQLite t
1a140 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 able has a uniqu
1a150 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
1a160 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
1a170 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
1a180 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 | "rowid"]. ^Th
1a190 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
1a1a0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
1a1b0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
1a1c0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
1a1d0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
1a1e0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
1a1f0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
1a200 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
1a210 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
1a220 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
1a230 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 ^If.** the table
1a240 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
1a250 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
1a260 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
1a270 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
1a280 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
1a290 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
1a2a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1a2b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
1a2c0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d [rowid] of the m
1a2d0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 ost recent.** su
1a2e0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
1a2f0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 ] into the datab
1a300 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 ase from the [da
1a310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a320 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
1a330 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 st argument. ^A
1a340 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
1a350 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 ion 3.7.7, this
1a360 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f routines.** reco
1a370 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 rds the last ins
1a380 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 ert rowid of bot
1a390 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 h ordinary table
1a3a0 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 s and [virtual t
1a3b0 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e ables]..** ^If n
1a3c0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
1a3d0 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 SERT]s.** have e
1a3e0 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 ver occurred on
1a3f0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f that database co
1a400 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 nnection, zero i
1a410 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
1a420 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 * ^(If an [INSER
1a430 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
1a440 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 a trigger or wi
1a450 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 thin a [virtual
1a460 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 table].** method
1a470 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 , then this rout
1a480 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ine will return
1a490 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
1a4a0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 he inserted.** r
1a4b0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ow as long as th
1a4c0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
1a4d0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f tual table metho
1a4e0 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a d is running..**
1a4f0 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
1a500 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
1a510 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e table method en
1a520 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 ds, the value re
1a530 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 turned .** by th
1a540 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 is routine rever
1a550 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 ts to what it wa
1a560 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 s before the tri
1a570 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a gger or virtual.
1a580 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 ** table method
1a590 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e began.)^.**.** ^
1a5a0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
1a5b0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
1a5c0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
1a5d0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
1a5e0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
1a5f0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
1a600 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
1a610 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
1a620 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
1a630 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 ^Thus INSERT OR
1a640 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 FAIL, INSERT OR
1a650 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 IGNORE, INSERT
1a660 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 OR ROLLBACK,.**
1a670 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 and INSERT OR AB
1a680 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e ORT make no chan
1a690 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 ges to the retur
1a6a0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a n value of this.
1a6b0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 ** routine when
1a6c0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 their insertion
1a6d0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 fails. ^(When I
1a6e0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
1a6f0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
1a700 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
1a710 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
1a720 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
1a730 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
1a740 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
1a750 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
1a760 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
1a770 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
1a780 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
1a790 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
1a7a0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
1a7b0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
1a7c0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
1a7d0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a terface.)^.**.**
1a7e0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 ^For the purpos
1a7f0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 es of this routi
1a800 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 ne, an [INSERT]
1a810 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
1a820 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 .** be successfu
1a830 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 l even if it is
1a840 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c subsequently rol
1a850 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
1a860 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
1a870 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 accessible to S
1a880 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 QL statements vi
1a890 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 a the.** [last_i
1a8a0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 nsert_rowid() SQ
1a8b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1a8c0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1a8d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
1a8e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
1a8f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
1a900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a910 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
1a920 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
1a930 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
1a940 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
1a950 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
1a960 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
1a970 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
1a980 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1a990 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1a9a0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1a9b0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
1a9c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
1a9d0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
1a9e0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
1a9f0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
1aa00 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
1aa10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1aa20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
1aa30 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
1aa40 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
1aa50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1aa60 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
1aa70 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
1aa80 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ified.**.** ^Thi
1aa90 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1aaa0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1aab0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 database rows t
1aac0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 hat were changed
1aad0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 .** or inserted
1aae0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 or deleted by th
1aaf0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
1ab00 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 completed SQL st
1ab10 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 atement.** on th
1ab20 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
1ab30 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
1ab40 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 d by the first p
1ab50 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f arameter..** ^(O
1ab60 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 nly changes that
1ab70 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 are directly sp
1ab80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b ecified by the [
1ab90 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 INSERT], [UPDATE
1aba0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 ],.** or [DELETE
1abb0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 ] statement are
1abc0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 counted. Auxili
1abd0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 ary changes caus
1abe0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 ed by.** trigger
1abf0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 s or [foreign ke
1ac00 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e y actions] are n
1ac10 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 ot counted.)^ Us
1ac20 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
1ac30 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1ac40 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 )] function to f
1ac50 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 ind the total nu
1ac60 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a mber of changes.
1ac70 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 ** including cha
1ac80 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 nges caused by t
1ac90 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 riggers and fore
1aca0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e ign key actions.
1acb0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 .**.** ^Changes
1acc0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 to a view that a
1acd0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 re simulated by
1ace0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 an [INSTEAD OF t
1acf0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e rigger].** are n
1ad00 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c ot counted. Onl
1ad10 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 y real table cha
1ad20 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 nges are counted
1ad30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 ..**.** ^(A "row
1ad40 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 change" is a ch
1ad50 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 ange to a single
1ad60 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 row of a single
1ad70 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 table.** caused
1ad80 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 by an INSERT, D
1ad90 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 ELETE, or UPDATE
1ada0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 statement. Row
1adb0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 s that.** are ch
1adc0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 anged as side ef
1add0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 fects of [REPLAC
1ade0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 E] constraint re
1adf0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c solution,.** rol
1ae00 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f lback, ABORT pro
1ae10 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 cessing, [DROP T
1ae20 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 ABLE], or by any
1ae30 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e other.** mechan
1ae40 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e isms do not coun
1ae50 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 t as direct row
1ae60 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a changes.)^.**.**
1ae70 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 A "trigger cont
1ae80 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 ext" is a scope
1ae90 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 of execution tha
1aea0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 t begins and.**
1aeb0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 ends with the sc
1aec0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 ript of a [CREAT
1aed0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
1aee0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 ger]. .** Most S
1aef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
1af00 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f e.** evaluated o
1af10 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 utside of any tr
1af20 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 igger. This is
1af30 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a the "top level".
1af40 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
1af50 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 xt. If a trigge
1af60 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 r fires from the
1af70 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a top level, a.**
1af80 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e new trigger con
1af90 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 text is entered
1afa0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e for the duration
1afb0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 of that one.**
1afc0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 trigger. Subtri
1afd0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 ggers create sub
1afe0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 contexts for the
1aff0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a ir duration..**.
1b000 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c ** ^Calling [sql
1b010 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 ite3_exec()] or
1b020 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1b030 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 recursively doe
1b040 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 s.** not create
1b050 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f a new trigger co
1b060 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ntext..**.** ^Th
1b070 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
1b080 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1b090 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 f direct row cha
1b0a0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d nges in the.** m
1b0b0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
1b0c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
1b0d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
1b0e0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a ithin the same.*
1b0f0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
1b100 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 t..**.** ^Thus,
1b110 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d when called from
1b120 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
1b130 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
1b140 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d turns the.** num
1b150 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
1b160 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
1b170 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
1b180 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
1b190 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 hat also occurre
1b1a0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 d at the top lev
1b1b0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 el. ^(Within th
1b1c0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 e body of a trig
1b1d0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 ger,.** the sqli
1b1e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e te3_changes() in
1b1f0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 terface can be c
1b200 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 alled to find th
1b210 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
1b220 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
1b230 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
1b240 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
1b250 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
1b260 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ** statement wit
1b270 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
1b280 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
1b290 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
1b2a0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 e number returne
1b2b0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
1b2c0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 de changes.** ca
1b2d0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 used by subtrigg
1b2e0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 ers since those
1b2f0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 have their own c
1b300 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ontext.)^.**.**
1b310 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
1b320 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
1b330 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
1b340 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
1b350 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
1b360 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 and the [change
1b370 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1b380 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
1b390 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
1b3a0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
1b3b0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
1b3c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
1b3d0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 hile [sqlite3_ch
1b3e0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
1b3f0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
1b400 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 ue returned.** i
1b410 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
1b420 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
1b430 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul..*/.SQLITE_AP
1b440 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 I int sqlite3_ch
1b450 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
1b460 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1b470 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f : Total Number O
1b480 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
1b490 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1b4a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1b4b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 number of row c
1b4c0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
1b4d0 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 [INSERT],.** [U
1b4e0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
1b4f0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 E] statements si
1b500 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 nce the [databas
1b510 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 e connection] wa
1b520 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 s opened..** ^(T
1b530 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 he count returne
1b540 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 d by sqlite3_tot
1b550 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 al_changes() inc
1b560 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 ludes all change
1b570 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 s.** from all [C
1b580 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
1b590 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 trigger] context
1b5a0 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 s and changes ma
1b5b0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 de by.** [foreig
1b5c0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 n key actions].
1b5d0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 However,.** the
1b5e0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 count does not i
1b5f0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 nclude changes u
1b600 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1b610 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
1b620 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f raints,.** do ro
1b630 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 llbacks or ABORT
1b640 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 processing, or
1b650 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f [DROP TABLE] pro
1b660 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a cessing. The.**
1b670 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
1b680 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 include rows of
1b690 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 views that fire
1b6a0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 an [INSTEAD OF t
1b6b0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 rigger],.** thou
1b6c0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 gh if the INSTEA
1b6d0 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b D OF trigger mak
1b6e0 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 es changes of it
1b6f0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 s own, those cha
1b700 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 nges .** are cou
1b710 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 nted.)^.** ^The
1b720 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1b730 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e anges() function
1b740 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e counts the chan
1b750 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a ges as soon as.*
1b760 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 * the statement
1b770 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 that makes them
1b780 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 is completed (wh
1b790 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
1b7a0 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 handle.** is pa
1b7b0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
1b7c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
1b7d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
1b7e0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ])..**.** See al
1b7f0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f so the [sqlite3_
1b800 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
1b810 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
1b820 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
1b830 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f ma], and the [to
1b840 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 tal_changes() SQ
1b850 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
1b860 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
1b870 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 thread makes ch
1b880 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d anges on the sam
1b890 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1b8a0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b ction.** while [
1b8b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1b8c0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
1b8d0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
1b8e0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 ue.** returned i
1b8f0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
1b900 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
1b910 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul..*/.SQLITE_AP
1b920 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f I int sqlite3_to
1b930 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 tal_changes(sqli
1b940 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1b950 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 PI3REF: Interrup
1b960 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 t A Long-Running
1b970 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 Query.**.** ^Th
1b980 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
1b990 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 es any pending d
1b9a0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f atabase operatio
1b9b0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a n to abort and.*
1b9c0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 * return at its
1b9d0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 earliest opportu
1b9e0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 nity. This routi
1b9f0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a ne is typically.
1ba00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 ** called in res
1ba10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 ponse to a user
1ba20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 action such as p
1ba30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 ressing "Cancel"
1ba40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 .** or Ctrl-C wh
1ba50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e ere the user wan
1ba60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 ts a long query
1ba70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c operation to hal
1ba80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 t.** immediately
1ba90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 ..**.** ^It is s
1baa0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
1bab0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 routine from a
1bac0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 thread different
1bad0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 from the.** thr
1bae0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 ead that is curr
1baf0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 ently running th
1bb00 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 e database opera
1bb10 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a tion. But it.**
1bb20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
1bb30 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
1bb40 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 e with a [databa
1bb50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
1bb60 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 hat.** is closed
1bb70 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 or might close
1bb80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 before sqlite3_i
1bb90 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 nterrupt() retur
1bba0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ns..**.** ^If an
1bbb0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
1bbc0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 s very nearly fi
1bbd0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 nished at the ti
1bbe0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 me when.** sqlit
1bbf0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 e3_interrupt() i
1bc00 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 s called, then i
1bc10 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 t might not have
1bc20 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a an opportunity.
1bc30 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 ** to be interru
1bc40 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 pted and might c
1bc50 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c ontinue to compl
1bc60 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e etion..**.** ^An
1bc70 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
1bc80 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
1bc90 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ed will return [
1bca0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
1bcb0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e ]..** ^If the in
1bcc0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
1bcd0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
1bce0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
1bcf0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
1bd00 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
1bd10 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
1bd20 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
1bd30 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
1bd40 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
1bd50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
1bd60 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 lly..**.** ^The
1bd70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1bd80 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 t(D) call is in
1bd90 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c effect until all
1bda0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
1bdb0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
1bdc0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 ents on [databas
1bdd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
1bde0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 complete. ^Any
1bdf0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e new SQL statemen
1be00 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
1be10 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
1be20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1be30 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 pt() call and be
1be40 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e fore the .** run
1be50 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 ning statements
1be60 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
1be70 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 interrupted as
1be80 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e if they had been
1be90 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f .** running prio
1bea0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
1beb0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1bec0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 l. ^New SQL sta
1bed0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1bee0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1bef0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 r the running st
1bf00 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 atement count re
1bf10 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a aches zero are.*
1bf20 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 * not effected b
1bf30 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e y the sqlite3_in
1bf40 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 terrupt()..** ^A
1bf50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
1bf60 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 _interrupt(D) th
1bf70 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 at occurs when t
1bf80 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e here are no runn
1bf90 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
1bfa0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 ments is a no-op
1bfb0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 and has no effe
1bfc0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d ct on SQL statem
1bfd0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
1bfe0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
1bff0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
1c000 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 rupt() call retu
1c010 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 rns..**.** If th
1c020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1c030 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 ction closes whi
1c040 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 le [sqlite3_inte
1c050 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 rrupt()].** is r
1c060 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 unning then bad
1c070 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 things will like
1c080 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 ly happen..*/.SQ
1c090 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
1c0a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1c0b0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
1c0c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
1c0d0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
1c0e0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d Statement Is Com
1c0f0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 plete.**.** Thes
1c100 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
1c110 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d seful during com
1c120 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 mand-line input
1c130 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 to determine if
1c140 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 the.** currently
1c150 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 entered text se
1c160 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f ems to form a co
1c170 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
1c180 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 ment or.** if ad
1c190 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 ditional input i
1c1a0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 s needed before
1c1b0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 sending the text
1c1c0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 into.** SQLite
1c1d0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 for parsing. ^T
1c1e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1c1f0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e turn 1 if the in
1c200 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 put string.** ap
1c210 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f pears to be a co
1c220 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 mplete SQL state
1c230 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d ment. ^A statem
1c240 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f ent is judged to
1c250 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 be.** complete
1c260 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 if it ends with
1c270 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 a semicolon toke
1c280 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 n and is not a p
1c290 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 refix of a.** we
1c2a0 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 ll-formed CREATE
1c2b0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 TRIGGER stateme
1c2c0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 nt. ^Semicolons
1c2d0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 that are embedd
1c2e0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 ed within.** str
1c2f0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 ing literals or
1c300 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 quoted identifie
1c310 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 r names or comme
1c320 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 nts are not.** i
1c330 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e ndependent token
1c340 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 s (they are part
1c350 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e of the token in
1c360 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a which they are.
1c370 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 ** embedded) and
1c380 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 thus do not cou
1c390 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e nt as a statemen
1c3a0 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e t terminator. ^
1c3b0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e Whitespace.** an
1c3c0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 d comments that
1c3d0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c follow the final
1c3e0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 semicolon are i
1c3f0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gnored..**.** ^T
1c400 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
1c410 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 turn 0 if the st
1c420 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d atement is incom
1c430 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a plete. ^If a.**
1c440 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1c450 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 on fails, then S
1c460 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 QLITE_NOMEM is r
1c470 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
1c480 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 These routines d
1c490 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 o not parse the
1c4a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 SQL statements t
1c4b0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 hus.** will not
1c4c0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 detect syntactic
1c4d0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 ally incorrect S
1c4e0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 QL..**.** ^(If S
1c4f0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 QLite has not be
1c500 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 en initialized u
1c510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e sing [sqlite3_in
1c520 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f itialize()] prio
1c530 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e r .** to invokin
1c540 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 g sqlite3_comple
1c550 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 te16() then sqli
1c560 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
1c570 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
1c580 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
1c590 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1c5a0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 16(). If that i
1c5b0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 nitialization fa
1c5c0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ils,.** then the
1c5d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
1c5e0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c om sqlite3_compl
1c5f0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 ete16() will be
1c600 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 non-zero.** rega
1c610 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
1c620 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 r or not the inp
1c630 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 ut SQL is comple
1c640 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te.)^.**.** The
1c650 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
1c660 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 3_complete()] mu
1c670 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
1c680 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 minated.** UTF-8
1c690 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 string..**.** T
1c6a0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
1c6b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
1c6c0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
1c6d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
1c6e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
1c6f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1c700 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 er..*/.SQLITE_AP
1c710 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
1c720 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
1c730 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f r *sql);.SQLITE_
1c740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1c750 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 complete16(const
1c760 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a void *sql);../*
1c770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
1c780 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 gister A Callbac
1c790 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 k To Handle SQLI
1c7a0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a TE_BUSY Errors.*
1c7b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1c7c0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 ne sets a callba
1c7d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ck function that
1c7e0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
1c7f0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e d whenever.** an
1c800 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
1c810 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 to open a datab
1c820 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 ase table that a
1c830 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a nother thread.**
1c840 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 or process has
1c850 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 locked..**.** ^I
1c860 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
1c870 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
1c880 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 n [SQLITE_BUSY]
1c890 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
1c8a0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 _BLOCKED].** is
1c8b0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
1c8c0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e tely upon encoun
1c8d0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e tering the lock.
1c8e0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 ^If the busy c
1c8f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f allback.** is no
1c900 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 t NULL, then the
1c910 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 callback might
1c920 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
1c930 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a two arguments..*
1c940 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1c950 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1c960 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
1c970 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
1c980 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 id* pointer whic
1c990 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 h.** is the thir
1c9a0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
1c9b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1c9c0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f er(). ^The seco
1c9d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
1c9e0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c * the busy handl
1c9f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
1ca00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d he number of tim
1ca10 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 es that the busy
1ca20 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 handler has.**
1ca30 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 been invoked for
1ca40 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 this locking ev
1ca50 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
1ca60 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 busy callback r
1ca70 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e eturns 0, then n
1ca80 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 o additional att
1ca90 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 empts are made t
1caa0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 o.** access the
1cab0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 database and [SQ
1cac0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
1cad0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
1cae0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 KED] is returned
1caf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
1cb00 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
1cb10 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f n-zero, then ano
1cb20 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ther attempt.**
1cb30 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
1cb40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 the database for
1cb50 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 reading and the
1cb60 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a cycle repeats..
1cb70 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e **.** The presen
1cb80 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e ce of a busy han
1cb90 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 dler does not gu
1cba0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 arantee that it
1cbb0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a will be invoked.
1cbc0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 ** when there is
1cbd0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e lock contention
1cbe0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 . ^If SQLite det
1cbf0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 ermines that inv
1cc00 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a oking the busy.*
1cc10 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 * handler could
1cc20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 result in a dead
1cc30 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f lock, it will go
1cc40 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 ahead and retur
1cc50 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1cc60 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f ** or [SQLITE_IO
1cc70 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 ERR_BLOCKED] ins
1cc80 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
1cc90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1cca0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 r..** Consider a
1ccb0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 scenario where
1ccc0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 one process is h
1ccd0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f olding a read lo
1cce0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 ck that.** it is
1ccf0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f trying to promo
1cd00 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 te to a reserved
1cd10 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 lock and.** a s
1cd20 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 econd process is
1cd30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 holding a reser
1cd40 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 ved lock that it
1cd50 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f is trying.** to
1cd60 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 promote to an e
1cd70 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 xclusive lock.
1cd80 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 The first proces
1cd90 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 s cannot proceed
1cda0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 .** because it i
1cdb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
1cdc0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 second and the
1cdd0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 second process c
1cde0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 annot.** proceed
1cdf0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
1ce00 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 locked by the fi
1ce10 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 rst. If both pr
1ce20 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b ocesses.** invok
1ce30 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c e the busy handl
1ce40 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c ers, neither wil
1ce50 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 l make any progr
1ce60 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c ess. Therefore,
1ce70 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 .** SQLite retur
1ce80 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ns [SQLITE_BUSY]
1ce90 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 for the first p
1cea0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 rocess, hoping t
1ceb0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c hat this.** will
1cec0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 induce the firs
1ced0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c t process to rel
1cee0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f ease its read lo
1cef0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 ck and allow.**
1cf00 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1cf10 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a ss to proceed..*
1cf20 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
1cf30 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 t busy callback
1cf40 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e is NULL..**.** ^
1cf50 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 The [SQLITE_BUSY
1cf60 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 ] error is conve
1cf70 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f rted to [SQLITE_
1cf80 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
1cf90 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
1cfa0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
1cfb0 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 f a large transa
1cfc0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 ction where all
1cfd0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 the.** changes w
1cfe0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f ill not fit into
1cff0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 the in-memory c
1d000 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 ache. SQLite wi
1d010 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f ll.** already ho
1d020 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f ld a RESERVED lo
1d030 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ck on the databa
1d040 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 se file, but it
1d050 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d needs.** to prom
1d060 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f ote this lock to
1d070 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 EXCLUSIVE so th
1d080 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 at it can spill
1d090 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 cache.** pages i
1d0a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
1d0b0 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 file without ha
1d0c0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 rm to concurrent
1d0d0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 .** readers. ^I
1d0e0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
1d0f0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
1d100 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
1d110 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
1d120 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
1d130 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
1d140 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
1d150 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
1d160 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
1d170 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
1d180 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
1d190 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
1d1a0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
1d1b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
1d1c0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 . ^This error c
1d1d0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a ode promotion.**
1d1e0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d forces an autom
1d1f0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 atic rollback of
1d200 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 the changes. S
1d210 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 ee the.** <a hre
1d220 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 f="/cvstrac/wiki
1d230 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c ?p=CorruptionFol
1d240 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 lowingBusyError"
1d250 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 >.** CorruptionF
1d260 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f ollowingBusyErro
1d270 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 r</a> wiki page
1d280 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e for a discussion
1d290 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 of why.** this
1d2a0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a is important..**
1d2b0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
1d2c0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
1d2d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 busy handler de
1d2e0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a fined for each.*
1d2f0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1d300 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e ection]. Settin
1d310 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e g a new busy han
1d320 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a dler clears any.
1d330 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
1d340 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e t handler.)^ ^N
1d350 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
1d360 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1d370 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c imeout()].** wil
1d380 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c l also set or cl
1d390 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e ear the busy han
1d3a0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 dler..**.** The
1d3b0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 busy callback sh
1d3c0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e ould not take an
1d3d0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 y actions which
1d3e0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 modify the.** da
1d3f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d400 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
1d410 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1d420 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f Any such actio
1d430 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ns.** result in
1d440 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
1d450 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 or..** .** A bus
1d460 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
1d470 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
1d480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d490 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
1d4a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
1d4b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
1d4c0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 y handler..*/.SQ
1d4d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1d4e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1d4f0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
1d500 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
1d510 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1d520 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
1d530 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a sy Timeout.**.**
1d540 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^This routine s
1d550 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 ets a [sqlite3_b
1d560 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 usy_handler | bu
1d570 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 sy handler] that
1d580 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 sleeps.** for a
1d590 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e specified amoun
1d5a0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 t of time when a
1d5b0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 table is locked
1d5c0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a . ^The handler.
1d5d0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
1d5e0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
1d5f0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
1d600 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
1d610 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
1d620 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 e accumulated.
1d630 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 ^After at least
1d640 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
1d650 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a s of sleeping,.*
1d660 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 * the handler re
1d670 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 turns 0 which ca
1d680 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 uses [sqlite3_st
1d690 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a ep()] to return.
1d6a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
1d6b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1d6c0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a R_BLOCKED]..**.*
1d6d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
1d6e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
1d6f0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
1d700 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
1d710 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
1d720 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
1d730 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
1d740 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1d750 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1d760 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
1d770 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1d780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
1d790 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 y any given mome
1d7a0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 nt. If another
1d7b0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 busy handler.**
1d7c0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 was defined (us
1d7d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
1d7e0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
1d7f0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
1d800 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
1d810 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
1d820 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
1d830 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ed.)^.*/.SQLITE_
1d840 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1d850 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c busy_timeout(sql
1d860 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a ite3*, int ms);.
1d870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1d880 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 Convenience Rou
1d890 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e tines For Runnin
1d8a0 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 g Queries.**.**
1d8b0 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 This is a legacy
1d8c0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
1d8d0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 is preserved for
1d8e0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1d8f0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 tibility..** Use
1d900 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
1d910 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d ce is not recomm
1d920 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 ended..**.** Def
1d930 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 inition: A <b>re
1d940 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 sult table</b> i
1d950 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 s memory data st
1d960 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 ructure created
1d970 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 by the.** [sqlit
1d980 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 e3_get_table()]
1d990 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 interface. A re
1d9a0 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 sult table recor
1d9b0 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 ds the.** comple
1d9c0 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 te query results
1d9d0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 from one or mor
1d9e0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a e queries..**.**
1d9f0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 The table conce
1da00 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 ptually has a nu
1da10 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 mber of rows and
1da20 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a columns. But.*
1da30 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 * these numbers
1da40 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 are not part of
1da50 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1da60 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a itself. These.
1da70 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f ** numbers are o
1da80 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 btained separate
1da90 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 ly. Let N be th
1daa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
1dab0 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 .** and M be the
1dac0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
1dad0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 ns..**.** A resu
1dae0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 lt table is an a
1daf0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
1db00 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
1db10 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1db20 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 s..** There are
1db30 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 (N+1)*M elements
1db40 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 in the array.
1db50 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e The first M poin
1db60 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f ters point.** to
1db70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1db80 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 strings that c
1db90 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 ontain the names
1dba0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e of the columns.
1dbb0 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
1dbc0 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f g entries all po
1dbd0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 int to query res
1dbe0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 ults. NULL valu
1dbf0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 es result.** in
1dc00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 NULL pointers.
1dc10 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 All other values
1dc20 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 are in their UT
1dc30 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
1dc40 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 ted.** string re
1dc50 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 presentation as
1dc60 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
1dc70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
1dc80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 ()]..**.** A res
1dc90 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 ult table might
1dca0 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f consist of one o
1dcb0 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c r more memory al
1dcc0 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 locations..** It
1dcd0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
1dce0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 pass a result ta
1dcf0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 ble directly to
1dd00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1dd10 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 ..** A result ta
1dd20 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 ble should be de
1dd30 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 allocated using
1dd40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
1dd50 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ble()]..**.** ^(
1dd60 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 As an example of
1dd70 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1dd80 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 e format, suppos
1dd90 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 e a query result
1dda0 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 .** is as follow
1ddb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1ddc0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1ddd0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 Name
1dde0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 | Age.**
1ddf0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------------
1de00 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 --------.**
1de10 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c Alice |
1de20 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 43.** Bo
1de30 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a b | 28.*
1de40 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 * Cindy
1de50 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 | 21.** </p
1de60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1de70 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 .**.** There are
1de80 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d two column (M==
1de90 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 2) and three row
1dea0 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 s (N==3). Thus
1deb0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 the.** result ta
1dec0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 ble has 8 entrie
1ded0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 s. Suppose the
1dee0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
1def0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 stored.** in an
1df00 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 array names azRe
1df10 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 sult. Then azRe
1df20 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 sult holds this
1df30 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c content:.**.** <
1df40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1df50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1df60 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 ult[0] = "Na
1df70 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 me";.** a
1df80 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d zResult[1] =
1df90 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Age";.**
1dfa0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 azResult[2
1dfb0 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
1dfc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1dfd0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a #91;3] = "43";.*
1dfe0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1dff0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 t[4] = "Bob"
1e000 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1e010 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 sult[5] = "2
1e020 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 8";.** az
1e030 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 Result[6] =
1e040 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
1e050 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1e060 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 7] = "21";.** </
1e070 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1e080 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 >)^.**.** ^The s
1e090 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1e0a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c () function eval
1e0b0 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 uates one or mor
1e0c0 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 e.** semicolon-s
1e0d0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 eparated SQL sta
1e0e0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a tements in the z
1e0f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
1e100 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f TF-8.** string o
1e110 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 f its 2nd parame
1e120 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
1e130 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 a result table t
1e140 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 o the.** pointer
1e150 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 given in its 3r
1e160 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
1e170 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 ** After the app
1e180 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e lication has fin
1e190 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 ished with the r
1e1a0 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 esult from sqlit
1e1b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a e3_get_table(),.
1e1c0 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 ** it must pass
1e1d0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1e1e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
1e1f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
1e200 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 in order to.**
1e210 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
1e220 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c ry that was mall
1e230 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f oced. Because o
1e240 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a f the way the.**
1e250 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1e260 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 ()] happens with
1e270 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 in sqlite3_get_t
1e280 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c able(), the call
1e290 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
1e2a0 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 must not try to
1e2b0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 call [sqlite3_fr
1e2c0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 ee()] directly.
1e2d0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 Only.** [sqlite
1e2e0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 3_free_table()]
1e2f0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 is able to relea
1e300 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
1e310 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c operly and safel
1e320 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
1e330 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1e340 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d interface is im
1e350 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 plemented as a w
1e360 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
1e370 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1e380 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f ]. The sqlite3_
1e390 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 get_table() rout
1e3a0 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 ine does not hav
1e3b0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 e access.** to a
1e3c0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ny internal data
1e3d0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 structures of S
1e3e0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 QLite. It uses
1e3f0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a only the public.
1e400 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 ** interface def
1e410 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 ined here. As a
1e420 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 consequence, er
1e430 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 rors that occur
1e440 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 in the.** wrappe
1e450 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 r layer outside
1e460 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 of the internal
1e470 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
1e480 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a call are not.**
1e490 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 reflected in su
1e4a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
1e4b0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
1e4c0 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c de()] or.** [sql
1e4d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
1e4e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1e4f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
1e500 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
1e510 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
1e520 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
1e530 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1e540 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
1e550 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
1e560 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
1e570 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
1e580 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
1e590 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
1e5a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
1e5b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1e5c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
1e5d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
1e5e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
1e5f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1e600 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
1e610 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
1e620 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
1e630 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
1e640 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
1e650 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
1e660 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 void sqlite3_fr
1e670 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
1e680 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
1e690 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
1e6a0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
1e6b0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
1e6c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1e6d0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
1e6e0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
1e6f0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
1e700 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
1e710 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1e720 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e library..**.** ^
1e730 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 The sqlite3_mpri
1e740 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ntf() and sqlite
1e750 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 3_vmprintf() rou
1e760 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 tines write thei
1e770 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 r.** results int
1e780 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
1e790 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
1e7a0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 malloc()]..** Th
1e7b0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
1e7c0 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 ed by these two
1e7d0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 routines should
1e7e0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 be.** released b
1e7f0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 y [sqlite3_free(
1e800 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 )]. ^Both routi
1e810 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 nes return a.**
1e820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
1e830 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1e840 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 )] is unable to
1e850 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a allocate enough.
1e860 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ** memory to hol
1e870 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 d the resulting
1e880 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 string..**.** ^(
1e890 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 The sqlite3_snpr
1e8a0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
1e8b0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e s similar to "sn
1e8c0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a printf()" from.*
1e8d0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 * the standard C
1e8e0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 library. The r
1e8f0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e esult is written
1e900 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 into the.** buf
1e910 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 fer supplied as
1e920 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1e930 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 eter whose size
1e940 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 is given by.** t
1e950 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1e960 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 er. Note that th
1e970 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a e order of the.*
1e980 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 * first two para
1e990 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 meters is revers
1e9a0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 ed from snprintf
1e9b0 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 ().)^ This is a
1e9c0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
1e9d0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
1e9e0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
1e9f0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
1ea00 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
1ea10 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f atibility. ^(No
1ea20 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c te also that sql
1ea30 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1ea40 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ** returns a poi
1ea50 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 nter to its buff
1ea60 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 er instead of th
1ea70 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
1ea80 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c haracters actual
1ea90 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ly written into
1eaa0 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 the buffer.)^ W
1eab0 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 e admit that.**
1eac0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
1ead0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e aracters written
1eae0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 would be a more
1eaf0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a useful return.*
1eb00 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 * value but we c
1eb10 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 annot change the
1eb20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1eb30 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1eb40 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 ntf().** now wit
1eb50 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f hout breaking co
1eb60 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
1eb70 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 ** ^As long as t
1eb80 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 he buffer size i
1eb90 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
1eba0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 ero, sqlite3_snp
1ebb0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 rintf().** guara
1ebc0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 ntees that the b
1ebd0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 uffer is always
1ebe0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
1ebf0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 ^The first.**
1ec00 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 parameter "n" is
1ec10 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 the total size
1ec20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 of the buffer, i
1ec30 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 ncluding space f
1ec40 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 or.** the zero t
1ec50 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 erminator. So t
1ec60 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e he longest strin
1ec70 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f g that can be co
1ec80 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 mpletely.** writ
1ec90 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 ten will be n-1
1eca0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
1ecb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
1ecc0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
1ecd0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 ne is a varargs
1ece0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 version of sqlit
1ecf0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a e3_snprintf()..*
1ed00 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1ed10 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e nes all implemen
1ed20 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 t some additiona
1ed30 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 l formatting.**
1ed40 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 options that are
1ed50 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 useful for cons
1ed60 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 tructing SQL sta
1ed70 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 tements..** All
1ed80 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 of the usual pri
1ed90 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 ntf() formatting
1eda0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 options apply.
1edb0 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 In addition, th
1edc0 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 ere.** is are "%
1edd0 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 q", "%Q", and "%
1ede0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a z" options..**.*
1edf0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f * ^(The %q optio
1ee00 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 n works like %s
1ee10 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 in that it subst
1ee20 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 itutes a nul-ter
1ee30 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
1ee40 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d g from the argum
1ee50 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 ent list. But %
1ee60 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 q also doubles e
1ee70 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 very '\'' charac
1ee80 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 ter..** %q is de
1ee90 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 signed for use i
1eea0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c nside a string l
1eeb0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f iteral.)^ By do
1eec0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 ubling each '\''
1eed0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 .** character it
1eee0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 escapes that ch
1eef0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f aracter and allo
1ef00 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 ws it to be inse
1ef10 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 rted into.** the
1ef20 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 string..**.** F
1ef30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 or example, assu
1ef40 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 me the string va
1ef50 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e riable zText con
1ef60 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f tains text as fo
1ef70 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1ef80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1ef90 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d * char *zText =
1efa0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 "It's a happy d
1efb0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!";.** </pre><
1efc0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1efd0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 ** One can use t
1efe0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 his text in an S
1eff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
1f000 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1f010 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1f020 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
1f030 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
1f040 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
1f050 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 able VALUES('%q'
1f060 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1f070 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1f080 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1f090 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1f0a0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1f0b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1f0c0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
1f0d0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 e %q format stri
1f0e0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 ng is used, the
1f0f0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 '\'' character i
1f100 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 n zText.** is es
1f110 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 caped and the SQ
1f120 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 L generated is a
1f130 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1f140 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1f150 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
1f160 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
1f170 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 ('It''s a happy
1f180 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e day!').** </pre>
1f190 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1f1a0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 .** This is corr
1f1b0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 ect. Had we use
1f1c0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 d %s instead of
1f1d0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 %q, the generate
1f1e0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 d SQL.** would h
1f1f0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 ave looked like
1f200 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f this:.**.** <blo
1f210 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1f220 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
1f230 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
1f240 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1f250 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1f260 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1f270 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 his second examp
1f280 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e le is an SQL syn
1f290 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 tax error. As a
1f2a0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f general rule yo
1f2b0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 u should.** alwa
1f2c0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 ys use %q instea
1f2d0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 d of %s when ins
1f2e0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f erting text into
1f2f0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
1f300 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 l..**.** ^(The %
1f310 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c Q option works l
1f320 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 ike %q except it
1f330 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c also adds singl
1f340 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a e quotes around.
1f350 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f ** the outside o
1f360 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 f the total stri
1f370 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c ng. Additionall
1f380 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 y, if the parame
1f390 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 ter in the.** ar
1f3a0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 gument list is a
1f3b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
1f3c0 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
1f3d0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
1f3e0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 ithout.** single
1f3f0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c quotes).)^ So,
1f400 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e for example, on
1f410 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a e could say:.**.
1f420 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1f430 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1f440 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
1f450 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
1f460 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
1f470 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a %Q)", zText);.**
1f480 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
1f490 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
1f4a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
1f4b0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
1f4c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1f4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 >.**.** The code
1f4e0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 above will rend
1f4f0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c er a correct SQL
1f500 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
1f510 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 e zSQL.** variab
1f520 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a le even if the z
1f530 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 Text variable is
1f540 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1f550 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a .**.** ^(The "%z
1f560 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 " formatting opt
1f570 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 ion works like "
1f580 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 %s" but with the
1f590 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 .** addition tha
1f5a0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 t after the stri
1f5b0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 ng has been read
1f5c0 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f and copied into
1f5d0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 .** the result,
1f5e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1f5f0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 is called on th
1f600 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 e input string.)
1f610 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ^.*/.SQLITE_API
1f620 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 char *sqlite3_mp
1f630 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
1f640 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 *,...);.SQLITE_A
1f650 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 PI char *sqlite3
1f660 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
1f670 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1f680 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1f690 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e *sqlite3_snprin
1f6a0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
1f6b0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a st char*, ...);.
1f6c0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
1f6d0 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e *sqlite3_vsnprin
1f6e0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
1f6f0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
1f700 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1f710 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
1f720 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d cation Subsystem
1f730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
1f740 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
1f750 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
1f760 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
1f770 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
1f780 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f790 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
1f7a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
1f7b0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
1f7c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
1f7d0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
1f7e0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
1f7f0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
1f800 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
1f810 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
1f820 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
1f830 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
1f840 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
1f850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1f860 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1f870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
1f880 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
1f890 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
1f8a0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
1f8b0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
1f8c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 ameter..** ^If s
1f8d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1f8e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
1f8f0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
1f900 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
1f910 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
1f920 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 pointer. ^If t
1f930 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 he parameter N t
1f940 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c o.** sqlite3_mal
1f950 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
1f960 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 negative then s
1f970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1f980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c returns.** a NUL
1f990 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1f9a0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
1f9b0 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
1f9c0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
1f9d0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
1f9e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
1f9f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
1fa00 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
1fa10 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
1fa20 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
1fa30 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 be reused. ^Th
1fa40 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 e sqlite3_free()
1fa50 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 routine is.** a
1fa60 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c no-op if is cal
1fa70 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
1fa80 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e pointer. Passin
1fa90 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
1faa0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 .** to sqlite3_f
1fab0 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 ree() is harmles
1fac0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 s. After being
1fad0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a freed, memory.**
1fae0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 should neither
1faf0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 be read nor writ
1fb00 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 ten. Even readi
1fb10 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 ng previously fr
1fb20 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 eed.** memory mi
1fb30 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 ght result in a
1fb40 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
1fb50 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 lt or other seve
1fb60 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d re error..** Mem
1fb70 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 ory corruption,
1fb80 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1fb90 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 ault, or other s
1fba0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d evere error.** m
1fbb0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 ight result if s
1fbc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
1fbd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e called with a n
1fbe0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 on-NULL pointer
1fbf0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 that.** was not
1fc00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
1fc10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1fc20 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1fc30 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 c()..**.** ^(The
1fc40 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1fc50 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
1fc60 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 empts to resize
1fc70 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 a.** prior memor
1fc80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
1fc90 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1fca0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 tes, where N is
1fcb0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 the.** second pa
1fcc0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 rameter. The me
1fcd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1fce0 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 to be resized is
1fcf0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 the first.** pa
1fd00 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 rameter.)^ ^ If
1fd10 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1fd20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1fd30 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
1fd40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
1fd50 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 en its behavior
1fd60 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
1fd70 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
1fd80 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 e3_malloc(N) whe
1fd90 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
1fda0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
1fdb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1fdc0 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 )..** ^If the se
1fdd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
1fde0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1fdf0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a c() is zero or.*
1fe00 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
1fe10 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
1fe20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
1fe30 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
1fe40 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 qlite3_free(P) w
1fe50 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 here P is the fi
1fe60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
1fe70 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1fe80 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f ()..** ^sqlite3_
1fe90 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
1fea0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1feb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1fec0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 on.** of at leas
1fed0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a t N bytes in siz
1fee0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 e or NULL if suf
1fef0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 ficient memory i
1ff00 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
1ff10 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 * ^If M is the s
1ff20 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 ize of the prior
1ff30 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 allocation, the
1ff40 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 n min(N,M) bytes
1ff50 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 .** of the prior
1ff60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 allocation are
1ff70 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 copied into the
1ff80 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 beginning of buf
1ff90 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 fer returned.**
1ffa0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c by sqlite3_reall
1ffb0 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 oc() and the pri
1ffc0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
1ffd0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 freed..** ^If s
1ffe0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1fff0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
20000 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c hen the prior al
20010 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e location.** is n
20020 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
20030 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
20040 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
20050 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c malloc() and sql
20060 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
20070 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
20080 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
20090 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
200a0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
200b0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
200c0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
200d0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
200e0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
200f0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
20100 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
20110 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
20120 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
20130 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
20140 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
20150 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
20160 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
20170 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
20180 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
20190 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
201a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
201b0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
201c0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
201d0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
201e0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
201f0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
20200 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
20210 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
20220 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
20230 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
20240 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
20250 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
20260 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
20270 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
20280 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
20290 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
202a0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
202b0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
202c0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
202d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
202e0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
202f0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
20300 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
20310 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
20320 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
20330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
20340 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
20350 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
20360 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
20370 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
20380 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
20390 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
203a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
203b0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
203c0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
203d0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
203e0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
203f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
20400 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
20410 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
20420 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
20430 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
20440 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
20450 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
20460 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
20470 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
20480 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
20490 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
204a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
204b0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
204c0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
204d0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
204e0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
204f0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
20500 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
20510 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
20520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
20530 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 lloc()]..*/.SQLI
20540 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
20550 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
20560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
20570 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
20580 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
20590 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
205a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
205b0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
205c0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
205d0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
205e0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 s.**.** SQLite p
205f0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 rovides these tw
20600 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 o interfaces for
20610 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 reporting on th
20620 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 e status.** of t
20630 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c he [sqlite3_mall
20640 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
20650 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 free()], and [sq
20660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
20670 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 .** routines, wh
20680 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 ich form the bui
20690 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
206a0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
206b0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 m..**.** ^The [s
206c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
206d0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 ed()] routine re
206e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
206f0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 of bytes.** of
20700 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 memory currently
20710 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 outstanding (ma
20720 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 lloced but not f
20730 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b reed)..** ^The [
20740 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
20750 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
20760 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
20770 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 maximum.** value
20780 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
20790 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
207a0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
207b0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 mark.** was las
207c0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 t reset. ^The v
207d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
207e0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
207f0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a y_used()] and.**
20800 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
20810 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e _highwater()] in
20820 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 clude any overhe
20830 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 ad.** added by S
20840 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
20850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
20860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
20870 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 ],.** but not ov
20880 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 erhead added by
20890 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 the any underlyi
208a0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 ng system librar
208b0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 y.** routines th
208c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c at [sqlite3_mall
208d0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a oc()] may call..
208e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
208f0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
20900 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
20910 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
20920 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d of.** [sqlite3_m
20930 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 emory_used()] if
20940 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
20950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
20960 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
20970 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 _highwater()] is
20980 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c true. ^The val
20990 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ue returned.** b
209a0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
209b0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 y_highwater(1)]
209c0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 is the high-wate
209d0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 r mark.** prior
209e0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f to the reset..*/
209f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
20a00 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
20a10 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 3_memory_used(vo
20a20 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
20a30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
20a40 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
20a50 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
20a60 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
20a70 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
20a80 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
20a90 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
20aa0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
20ab0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
20ac0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
20ad0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
20ae0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
20af0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
20b00 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
20b10 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
20b20 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
20b30 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
20b40 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
20b50 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
20b60 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
20b70 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
20b80 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
20b90 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
20ba0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
20bb0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
20bc0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
20bd0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
20be0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
20bf0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
20c00 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
20c10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
20c20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
20c30 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
20c40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
20c50 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ffer P..**.** ^T
20c60 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
20c70 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e is routine is in
20c80 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e voked (either in
20c90 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a ternally or by.*
20ca0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
20cb0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 n) the PRNG is s
20cc0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
20cd0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a omness obtained.
20ce0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ** from the xRan
20cf0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
20d00 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
20d10 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
20d20 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 ct..** ^On all s
20d30 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
20d40 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
20d50 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
20d60 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
20d70 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
20d80 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
20d90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
20da0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
20db0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 method..*/.SQLI
20dc0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
20dd0 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 te3_randomness(i
20de0 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a nt N, void *P);.
20df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20e00 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 Compile-Time Au
20e10 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c thorization Call
20e20 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 backs.**.** ^Thi
20e30 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
20e40 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ers an authorize
20e50 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
20e60 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
20e70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
20e80 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
20e90 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
20ea0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 ument..** ^The a
20eb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20ec0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
20ed0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
20ee0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
20ef0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
20f00 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
20f10 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
20f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20f30 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
20f40 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
20f50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
20f60 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 re16_v2()]. ^At
20f70 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e various.** poin
20f80 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f ts during the co
20f90 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 mpilation proces
20fa0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 s, as logic is b
20fb0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 eing created.**
20fc0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
20fd0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 us actions, the
20fe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20ff0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 ack is invoked t
21000 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 o.** see if thos
21010 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c e actions are al
21020 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 lowed. ^The aut
21030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21040 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
21050 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f n [SQLITE_OK] to
21060 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f allow the actio
21070 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 n, [SQLITE_IGNOR
21080 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 E] to disallow t
21090 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 he.** specific a
210a0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 ction but allow
210b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
210c0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f t to continue to
210d0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c be.** compiled,
210e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
210f0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 ] to cause the e
21100 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d ntire SQL statem
21110 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a ent to be.** rej
21120 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 ected with an er
21130 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 ror. ^If the au
21140 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21150 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 k returns.** any
21160 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
21170 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 n [SQLITE_IGNORE
21180 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
21190 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
211a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 .** then the [sq
211b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
211c0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
211d0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
211e0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 gered.** the aut
211f0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
21200 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
21210 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 message..**.** W
21220 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
21230 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
21240 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 _OK], that means
21250 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
21260 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f * requested is o
21270 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 k. ^When the ca
21280 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
21290 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 SQLITE_DENY], th
212a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
212b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
212c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
212d0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 hat triggered th
212e0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
212f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
21300 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 n error message
21310 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a explaining that.
21320 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e ** access is den
21330 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ied. .**.** ^The
21340 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
21350 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
21360 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
21370 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 copy of the thi
21380 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
21390 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
213a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
213b0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 interface. ^The
213c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
213d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 .** to the callb
213e0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ack is an intege
213f0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c r [SQLITE_COPY |
21400 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 action code] th
21410 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
21420 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
21430 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
21440 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 orized. ^The thi
21450 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 rd through sixth
21460 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
21470 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 o the callback a
21480 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 re zero-terminat
21490 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 ed strings that
214a0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e contain addition
214b0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 al.** details ab
214c0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 out the action t
214d0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
214e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 .**.** ^If the a
214f0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
21500 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 QLITE_READ].** a
21510 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
21520 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
21530 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 IGNORE] then the
21540 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
21550 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 atement] stateme
21560 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 nt is constructe
21570 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a d to substitute.
21580 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 ** a NULL value
21590 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 in place of the
215a0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
215b0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 t would have.**
215c0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 been read if [SQ
215d0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 LITE_OK] had bee
215e0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 n returned. The
215f0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
21600 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 .** return can b
21610 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 e used to deny a
21620 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 n untrusted user
21630 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 access to indiv
21640 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 idual.** columns
21650 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 of a table..**
21660 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
21670 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 ode is [SQLITE_D
21680 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 ELETE] and the c
21690 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
216a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ** [SQLITE_IGNOR
216b0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c E] then the [DEL
216c0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 ETE] operation p
216d0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a roceeds but the.
216e0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 ** [truncate opt
216f0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 imization] is di
21700 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 sabled and all r
21710 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 ows are deleted
21720 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a individually..**
21730 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 .** An authorize
21740 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b r is used when [
21750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
21760 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 | preparing].**
21770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 SQL statements f
21780 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 rom an untrusted
21790 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 source, to ensu
217a0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 re that the SQL
217b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f statements.** do
217c0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 not try to acce
217d0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 ss data they are
217e0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 not allowed to
217f0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 see, or that the
21800 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 y do not.** try
21810 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 to execute malic
21820 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 ious statements
21830 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 that damage the
21840 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a database. For.*
21850 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 * example, an ap
21860 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c plication may al
21870 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e low a user to en
21880 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a ter arbitrary.**
21890 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 SQL queries for
218a0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 evaluation by a
218b0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 database. But
218c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
218d0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
218e0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 the user to be
218f0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 able to make arb
21900 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 itrary changes t
21910 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 o the.** databas
21920 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 e. An authorize
21930 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 r could then be
21940 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 put in place whi
21950 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 le the.** user-e
21960 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 ntered SQL is be
21970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
21980 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d pare | prepared]
21990 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f that.** disallo
219a0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 ws everything ex
219b0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 cept [SELECT] st
219c0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
219d0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
219e0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 t need to proces
219f0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 s SQL from untru
21a00 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 sted sources.**
21a10 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 might also consi
21a20 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 der lowering res
21a30 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 ource limits usi
21a40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
21a50 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 t()].** and limi
21a60 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 ting database si
21a70 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 ze using the [ma
21a80 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
21a90 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 RAGMA].** in add
21aa0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 ition to using a
21ab0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a n authorizer..**
21ac0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e .** ^(Only a sin
21ad0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 gle authorizer c
21ae0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f an be in place o
21af0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e n a database con
21b00 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 nection.** at a
21b10 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c time. Each call
21b20 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f to sqlite3_set_
21b30 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 authorizer overr
21b40 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 ides the.** prev
21b50 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 ious call.)^ ^D
21b60 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
21b70 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
21b80 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
21b90 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
21ba0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
21bb0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
21bc0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
21bd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
21be0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
21bf0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
21c00 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
21c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
21c20 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
21c30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
21c40 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
21c50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
21c60 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
21c70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
21c80 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
21c90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
21ca0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
21cb0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
21cc0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
21cd0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 raph..**.** ^Whe
21ce0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
21cf0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 re_v2()] is used
21d00 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 to prepare a st
21d10 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 atement, the.**
21d20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 statement might
21d30 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 be re-prepared d
21d40 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 uring [sqlite3_s
21d50 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 tep()] due to a
21d60 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 .** schema chang
21d70 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 e. Hence, the a
21d80 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
21d90 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 d ensure that th
21da0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 e.** correct aut
21db0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21dc0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 remains in plac
21dd0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 e during the [sq
21de0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
21df0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 *.** ^Note that
21e00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
21e10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
21e20 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a ed only during.*
21e30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
21e40 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
21e50 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a iants. Authoriz
21e60 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 ation is not.**
21e70 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 performed during
21e80 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 statement evalu
21e90 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 ation in [sqlite
21ea0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 3_step()], unles
21eb0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 s.** as stated i
21ec0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 n the previous p
21ed0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 aragraph, sqlite
21ee0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 3_step() invokes
21ef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
21f00 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 are_v2() to repr
21f10 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
21f20 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 t after a schema
21f30 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 change..*/.SQLI
21f40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
21f50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21f60 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 r(. sqlite3*,.
21f70 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f int (*xAuth)(vo
21f80 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
21f90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
21fa0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
21fb0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 t char*),. void
21fc0 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a *pUserData.);..
21fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21fe0 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 Authorizer Retur
21ff0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 n Codes.**.** Th
22000 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
22010 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
22020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
22030 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a function] must.*
22040 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 * return either
22050 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f [SQLITE_OK] or o
22060 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 ne of these two
22070 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 constants in ord
22080 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 er.** to signal
22090 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f SQLite whether o
220a0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e r not the action
220b0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 is permitted.
220c0 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 See the.** [sqli
220d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
220e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
220f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
22100 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
22110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
22120 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
22130 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 LITE_IGNORE is a
22140 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 lso used as a [S
22150 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c QLITE_ROLLBACK |
22160 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a return code].**
22170 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
22180 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
22190 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ict()] interface
221a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
221b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
221c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
221d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
221e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
221f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
22200 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
22210 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
22220 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
22230 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
22240 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
22250 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
22260 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
22270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
22280 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
22290 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
222a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
222b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
222c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
222d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 certain SQL sta
222e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 tement actions.
222f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
22300 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
22310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
22320 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
22330 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
22340 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 at action is bei
22350 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ng authorized.
22360 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e These are the in
22370 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 teger action cod
22380 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 es that.** the a
22390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
223a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 ck may be passed
223b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 ..**.** These ac
223c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 tion code values
223d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 signify what ki
223e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 nd of operation
223f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 is to be.** auth
22400 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
22410 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
22420 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
22430 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
22440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 back function wi
22450 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
22460 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
22470 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
22480 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
22490 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
224a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
224b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 ^(The 5th parame
224c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
224d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
224e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
224f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
22500 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
22510 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
22520 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 cable.)^ ^The 6
22530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
22540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
22550 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
22560 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
22570 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
22580 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
22590 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
225a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
225b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
225c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
225d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
225e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
225f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
22600 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
22610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
22630 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
22640 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
22650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
22660 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
22670 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
22680 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
22690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
226a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
226b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
226c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
226d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
226e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
226f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
22700 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
22710 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
22720 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
22730 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
22750 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
22760 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
22770 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
22780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22790 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
227a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
227b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
227c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
227d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
227e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
227f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
22800 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
22810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
22820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22830 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22840 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
22850 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
22860 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
22870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22880 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
22890 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
228a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
228b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
228c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
228d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
228e0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
228f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22920 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
22930 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
22940 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
22950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22970 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
22980 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
22990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
229a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
229b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
229c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
229d0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
229e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
229f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22a10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
22a20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
22a30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22a40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
22a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22a60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
22a70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
22a80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
22a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22ab0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
22ac0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
22ad0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
22ae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22b00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
22b10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
22b20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
22b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
22b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
22b50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
22b60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
22b70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
22b80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
22ba0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
22bb0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
22bc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
22bd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
22bf0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
22c00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
22c10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
22c20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
22c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
22c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22c50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
22c60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
22c70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
22c80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
22c90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
22ca0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
22cb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
22cc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22cd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
22ce0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
22cf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
22d00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
22d10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22d20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
22d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
22d40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22d50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
22d60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
22d70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
22d80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
22d90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
22da0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22db0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22dc0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
22dd0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
22de0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
22df0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
22e00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22e10 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
22e20 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
22e30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
22e40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22e50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22e60 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
22e70 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
22e80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
22e90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22ea0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22eb0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
22ec0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
22ed0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22ee0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22ef0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22f00 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
22f10 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
22f20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22f30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
22f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22f50 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
22f60 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
22f70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
22f80 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
22f90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22fa0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
22fb0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
22fc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
22fd0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
22fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22ff0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 SAVEPOINT
23000 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 32 /* Ope
23010 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 ration Sav
23020 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a epoint Name */.
23030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
23040 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
23050 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
23060 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f onger used */../
23070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
23080 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 racing And Profi
23090 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ling Functions.*
230a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
230b0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
230c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
230d0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
230e0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
230f0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
23100 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
23110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
23120 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
23130 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
23140 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
23150 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 3_trace() is inv
23160 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f oked at.** vario
23170 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e us times when an
23180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
23190 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b s being run by [
231a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
231b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
231c0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 _trace() callbac
231d0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 k is invoked wit
231e0 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 h a UTF-8 render
231f0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 ing of the.** SQ
23200 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
23210 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e as the statemen
23220 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 t first begins e
23230 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 xecuting..** ^(A
23240 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 dditional sqlite
23250 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
23260 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a cks might occur.
23270 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 ** as each trigg
23280 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 ered subprogram
23290 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 is entered. The
232a0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 callbacks for t
232b0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 riggers.** conta
232c0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 in a UTF-8 SQL c
232d0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e omment that iden
232e0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 tifies the trigg
232f0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er.)^.**.** ^The
23300 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
23310 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
23320 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
23330 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
23340 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 as each SQL sta
23350 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e tement finishes.
23360 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 ^The profile c
23370 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 allback contains
23380 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c .** the original
23390 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
233a0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 and an estimate
233b0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 of wall-clock ti
233c0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e me.** of how lon
233d0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 g that statement
233e0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e took to run. ^
233f0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
23400 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 back.** time is
23410 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f in units of nano
23420 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 seconds, however
23430 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 the current imp
23440 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 lementation.** i
23450 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f s only capable o
23460 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 f millisecond re
23470 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 solution so the
23480 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 six least signif
23490 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 icant.** digits
234a0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 in the time are
234b0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 meaningless. Fu
234c0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
234d0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 SQLite.** might
234e0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 provide greater
234f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 resolution on t
23500 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c he profiler call
23510 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 back. The.** sq
23520 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
23530 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 function is cons
23540 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e idered experimen
23550 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 tal and is.** su
23560 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
23570 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
23580 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ns of SQLite..*/
23590 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
235a0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 *sqlite3_trace(
235b0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a sqlite3*, void(*
235c0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
235d0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
235e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
235f0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
23600 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 AL void *sqlite3
23610 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 _profile(sqlite3
23620 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f *,. void(*xPro
23630 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 file)(void*,cons
23640 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f t char*,sqlite3_
23650 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b uint64), void*);
23660 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23670 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 : Query Progress
23680 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a Callbacks.**.**
23690 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 ^The sqlite3_pr
236a0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 ogress_handler(D
236b0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 ,N,X,P) interfac
236c0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c e causes the cal
236d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
236e0 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 n X to be invoke
236f0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 d periodically d
23700 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 uring long runni
23710 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ng calls to.** [
23720 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
23730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
23740 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 ] and [sqlite3_g
23750 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a et_table()] for.
23760 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
23770 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 ection D. An ex
23780 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
23790 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
237a0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
237b0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
237c0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
237d0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 *.** ^The parame
237e0 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 ter P is passed
237f0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f through as the o
23800 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
23810 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 the .** callbac
23820 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e k function X. ^
23830 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 The parameter N
23840 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
23850 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 .** [virtual ma
23860 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f chine instructio
23870 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 ns] that are eva
23880 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 luated between s
23890 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 uccessive.** inv
238a0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
238b0 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a callback X..**.*
238c0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
238d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
238e0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
238f0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
23900 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
23910 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
23920 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
23930 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
23940 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
23950 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
23960 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
23970 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
23980 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
23990 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
239a0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
239b0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
239c0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
239d0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
239e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
239f0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
23a00 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
23a10 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
23a20 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
23a30 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
23a40 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
23a50 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
23a60 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
23a70 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
23a80 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
23a90 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
23aa0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
23ab0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
23ac0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
23ad0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
23ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23af0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
23b00 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
23b10 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
23b20 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
23b30 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
23b40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
23b50 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
23b60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
23b70 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
23b80 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
23b90 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
23ba0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 agraph..**.*/.SQ
23bb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
23bc0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
23bd0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
23be0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 int, int(*)(voi
23bf0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a d*), void*);../*
23c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 .** CAPI3REF: Op
23c10 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 ening A New Data
23c20 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
23c30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
23c40 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 tines open an SQ
23c50 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 Lite database fi
23c60 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 le as specified
23c70 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e by the .** filen
23c80 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
23c90 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
23ca0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
23cb0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
23cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
23cd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
23ce0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
23cf0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
23d00 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
23d10 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
23d20 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
23d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
23d40 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
23d50 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
23d60 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
23d70 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
23d80 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
23d90 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
23da0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
23db0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
23dc0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
23dd0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
23de0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
23df0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
23e00 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
23e10 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
23e20 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
23e30 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
23e40 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
23e50 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
23e60 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
23e70 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
23e80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
23e90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
23ea0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
23eb0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
23ec0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
23ed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
23ee0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
23ef0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
23f00 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
23f10 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
23f20 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
23f30 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
23f40 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
23f50 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
23f60 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
23f70 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
23f80 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
23f90 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
23fa0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
23fb0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
23fc0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f if.** sqlite3_o
23fd0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
23fe0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 _open_v2() is ca
23ff0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
24000 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
24010 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 byte order if s
24020 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 qlite3_open16()
24030 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 is used..**.** W
24040 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e hether or not an
24050 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
24060 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c en it is opened,
24070 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 resources.** as
24080 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
24090 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
240a0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 ection] handle s
240b0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 hould be release
240c0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 d by.** passing
240d0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
240e0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 lose()] when it
240f0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 is no longer req
24100 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uired..**.** The
24110 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24120 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 () interface wor
24130 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
24140 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 open().** except
24150 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 that it accepts
24160 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
24170 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 parameters for a
24180 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f dditional contro
24190 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 l.** over the ne
241a0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
241b0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c ction. ^(The fl
241c0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f ags parameter to
241d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
241e0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f _v2() can take o
241f0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c ne of.** the fol
24200 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c lowing three val
24210 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 ues, optionally
24220 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 combined with th
24230 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 e .** [SQLITE_OP
24240 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 EN_NOMUTEX], [SQ
24250 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
24260 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
24270 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c EN_SHAREDCACHE],
24280 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
24290 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 _PRIVATECACHE],
242a0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f and/or [SQLITE_O
242b0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 PEN_URI] flags:)
242c0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ^.**.** <dl>.**
242d0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
242e0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 EN_READONLY]</dt
242f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
24300 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
24310 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 in read-only mod
24320 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 e. If the datab
24330 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ase does not.**
24340 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 already exist, a
24350 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
24360 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ned.</dd>)^.**.*
24370 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
24380 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c OPEN_READWRITE]<
24390 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
243a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
243b0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
243c0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f nd writing if po
243d0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 ssible, or readi
243e0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 ng.** only if th
243f0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 e file is write
24400 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 protected by the
24410 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
24420 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a m. In either.**
24430 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 case the databa
24440 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 se must already
24450 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 exist, otherwise
24460 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
24470 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a urned.</dd>)^.**
24480 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
24490 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
244a0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
244b0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a _CREATE]</dt>.**
244c0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
244d0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
244e0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
244f0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 ing, and is crea
24500 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 ted if.** it doe
24510 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 s not already ex
24520 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 ist. This is the
24530 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 behavior that i
24540 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f s always used fo
24550 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
24560 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
24570 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e open16().</dd>)^
24580 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </dl>.**.**
24590 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
245a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
245b0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 open_v2() is not
245c0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 one of the.** c
245d0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 ombinations show
245e0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c n above optional
245f0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
24600 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 other.** [SQLIT
24610 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 E_OPEN_READONLY
24620 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 | SQLITE_OPEN_*
24630 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 bits].** then th
24640 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
24650 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
24660 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f If the [SQLITE_O
24670 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 PEN_NOMUTEX] fla
24680 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 g is set, then t
24690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
246a0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 ection.** opens
246b0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 in the multi-thr
246c0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d ead [threading m
246d0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 ode] as long as
246e0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 the single-threa
246f0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f d.** mode has no
24700 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f t been set at co
24710 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
24720 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 art-time. ^If t
24730 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
24740 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c EN_FULLMUTEX] fl
24750 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 ag is set then t
24760 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
24770 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 ection opens.**
24780 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 in the serialize
24790 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
247a0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 e] unless single
247b0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 -thread was.** p
247c0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 reviously select
247d0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ed at compile-ti
247e0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
247f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
24800 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
24810 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 HE] flag causes
24820 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
24830 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a nection to be.**
24840 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 eligible to use
24850 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d [shared cache m
24860 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 ode], regardless
24870 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
24880 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 ot shared.** cac
24890 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 he is enabled us
248a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 ing [sqlite3_ena
248b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
248c0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 ()]. ^The.** [S
248d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
248e0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 TECACHE] flag ca
248f0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
24900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
24910 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 not.** participa
24920 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 te in [shared ca
24930 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 che mode] even i
24940 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e f it is enabled.
24950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 .**.** ^The four
24960 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
24970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24980 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 ) is the name of
24990 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
249a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 _vfs] object tha
249b0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 t defines the op
249c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 erating system i
249d0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a nterface that.**
249e0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
249f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f e connection sho
24a00 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 uld use. ^If th
24a10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
24a20 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 er is.** a NULL
24a30 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 pointer then the
24a40 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
24a50 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 3_vfs] object is
24a60 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 used..**.** ^If
24a70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
24a80 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 ":memory:", the
24a90 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
24aa0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 porary in-memory
24ab0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 database.** is
24ac0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 created for the
24ad0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 connection. ^Th
24ae0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 is in-memory dat
24af0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 abase will vanis
24b00 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 h when.** the da
24b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24b20 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 n is closed. Fu
24b30 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
24b40 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a SQLite might.**
24b50 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 make use of add
24b60 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 itional special
24b70 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 filenames that b
24b80 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a egin with the ":
24b90 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 " character..**
24ba0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 It is recommende
24bb0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 d that when a da
24bc0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
24bd0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 actually does be
24be0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a gin with.** a ":
24bf0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 " character you
24c00 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 should prefix th
24c10 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 e filename with
24c20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 a pathname such
24c30 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 as.** "./" to av
24c40 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a oid ambiguity..*
24c50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
24c60 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 ename is an empt
24c70 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 y string, then a
24c80 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
24c90 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 ary.** on-disk d
24ca0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
24cb0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 created. ^This
24cc0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 private database
24cd0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f will be.** auto
24ce0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 matically delete
24cf0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 d as soon as the
24d00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24d10 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a tion is closed..
24d20 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
24d30 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 names in sqlite3
24d40 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 _open()]] <h3>UR
24d50 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e I Filenames</h3>
24d60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 .**.** ^If [URI
24d70 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 filename] interp
24d80 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 retation is enab
24d90 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c led, and the fil
24da0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a ename argument.*
24db0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 * begins with "f
24dc0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 ile:", then the
24dd0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 filename is inte
24de0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 rpreted as a URI
24df0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 . ^URI.** filena
24e00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
24e10 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 n is enabled if
24e20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
24e30 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a _URI] flag is.**
24e40 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 set in the four
24e50 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
24e60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
24e70 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a , or if it has.*
24e80 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 * been enabled g
24e90 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 lobally using th
24ea0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
24eb0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 _URI] option wit
24ec0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 h the.** [sqlite
24ed0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 3_config()] meth
24ee0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 od or by the [SQ
24ef0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f LITE_USE_URI] co
24f00 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
24f10 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 n..** As of SQLi
24f20 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 te version 3.7.7
24f30 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 , URI filename i
24f40 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
24f50 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 turned off.** b
24f60 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 y default, but f
24f70 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
24f80 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 f SQLite might e
24f90 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 nable URI filena
24fa0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 me.** interpreta
24fb0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e tion by default.
24fc0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 See "[URI file
24fd0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 names]" for addi
24fe0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
24ff0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 ation..**.** URI
25000 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 filenames are p
25010 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 arsed according
25020 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 to RFC 3986. ^If
25030 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e the URI contain
25040 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 s an.** authorit
25050 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 y, then it must
25060 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 be either an emp
25070 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 ty string or the
25080 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 string .** "loc
25090 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 alhost". ^If the
250a0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f authority is no
250b0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e t an empty strin
250c0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 g or "localhost"
250d0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 , an .** error i
250e0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 s returned to th
250f0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 e caller. ^The f
25100 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e ragment componen
25110 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a t of a URI, if .
25120 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 ** present, is i
25130 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 gnored..**.** ^S
25140 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 QLite uses the p
25150 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ath component of
25160 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 the URI as the
25170 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b name of the disk
25180 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 file.** which c
25190 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 ontains the data
251a0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 base. ^If the pa
251b0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 th begins with a
251c0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 '/' character,
251d0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 .** then it is i
251e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e nterpreted as an
251f0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 absolute path.
25200 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 ^If the path doe
25210 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 s not begin .**
25220 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e with a '/' (mean
25230 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 ing that the aut
25240 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 hority section i
25250 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
25260 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 he URI).** then
25270 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 the path is inte
25280 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c rpreted as a rel
25290 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 ative path. .**
252a0 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 ^On windows, the
252b0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 first component
252c0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 of an absolute
252d0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 path .** is a dr
252e0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f ive specificatio
252f0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a n (e.g. "C:")..*
25300 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 *.** [[core URI
25310 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
25320 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 ]].** The query
25330 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
25340 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 RI may contain p
25350 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 arameters that a
25360 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a re interpreted.*
25370 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 * either by SQLi
25380 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 te itself, or by
25390 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d a [VFS | custom
253a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
253b0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ion]..** SQLite
253c0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66 interprets the f
253d0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71 ollowing three q
253e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a uery parameters:
253f0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
25400 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e <li> <b>vfs</b>
25410 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 : ^The "vfs" par
25420 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 ameter may be us
25430 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ed to specify th
25440 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 e name of.**
25450 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 a VFS object th
25460 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 at provides the
25470 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
25480 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
25490 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 should.** be
254a0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 used to access
254b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
254c0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 e on disk. ^If t
254d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 his option is se
254e0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 t to.** an e
254f0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 mpty string the
25500 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 default VFS obje
25510 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 ct is used. ^Spe
25520 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
25530 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 wn.** VFS is
25540 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 an error. ^If s
25550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25560 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
25570 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a vfs option is.*
25580 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 * present, t
25590 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 hen the VFS spec
255a0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 ified by the opt
255b0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 ion takes preced
255c0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 ence over.**
255d0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
255e0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
255f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25600 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
25610 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
25620 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 mode</b>: ^(The
25630 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d mode parameter m
25640 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
25650 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a her "ro", "rw",.
25660 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 ** "rwc", or
25670 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d "memory". Attem
25680 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 pting to set it
25690 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c to any other val
256a0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 ue is.** an
256b0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 error)^. .**
256c0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 ^If "ro" is spe
256d0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
256e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
256f0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ned for read-onl
25700 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 y .** access
25710 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 , just as if the
25720 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
25730 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 ADONLY] flag had
25740 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 been set in the
25750 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 .** third a
25760 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
25770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 e3_open_v2(). ^I
25780 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
25790 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
257a0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then t
257b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
257c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
257d0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
257e0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
257f0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
25800 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
25810 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
25820 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
25830 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
25840 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
25850 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
25860 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
25870 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
25880 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
25890 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
258a0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
258b0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
258c0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
258d0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
258e0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
258f0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
25900 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
25910 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
25920 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
25930 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
25940 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
25950 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
25960 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
25970 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
25980 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
25990 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
259a0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
259b0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
259c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
259d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
259e0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
259f0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
25a00 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
25a10 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
25a20 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
25a30 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
25a40 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
25a50 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
25a60 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
25a70 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
25a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
25a90 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
25aa0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
25ab0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
25ac0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
25ad0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
25ae0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
25af0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
25b00 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
25b10 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
25b20 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
25b30 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
25b40 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
25b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
25b60 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
25b70 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
25b80 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
25b90 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
25ba0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
25bb0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
25bc0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 ehavior requeste
25bd0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 d by setting.**
25be0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
25bf0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 PRIVATECACHE or
25c00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
25c10 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a EDCACHE flag..**
25c20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 </ul>.**.** ^Sp
25c30 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
25c40 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e own parameter in
25c50 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f the query compo
25c60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 nent of a URI is
25c70 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 not an.** error
25c80 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
25c90 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
25ca0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 ht understand ad
25cb0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a ditional query.*
25cc0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 * parameters. S
25cd0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d ee "[query param
25ce0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 eters with speci
25cf0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 al meaning to SQ
25d00 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 Lite]" for.** ad
25d10 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
25d20 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 tion..**.** [[UR
25d30 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 I filename examp
25d40 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 les]] <h3>URI fi
25d50 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c lename examples<
25d60 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c /h3>.**.** <tabl
25d70 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 e border="1" ali
25d80 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 gn=center cellpa
25d90 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e dding=5>.** <tr>
25da0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d <th> URI filenam
25db0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a es <th> Results.
25dc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
25dd0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a :data.db <td> .*
25de0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
25df0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
25e00 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
25e10 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 t directory..**
25e20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
25e30 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
25e40 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <br>.**
25e50 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 file:///home/fr
25e60 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
25e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
25e80 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f e://localhost/ho
25e90 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
25ea0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 <br> <td> .**
25eb0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
25ec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f database file "/
25ed0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
25ee0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 b"..** <tr><td>
25ef0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f file://darkstar/
25f00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
25f10 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
25f20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 An error. "d
25f30 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 arkstar" is not
25f40 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 a recognized aut
25f50 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c hority..** <tr><
25f60 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d td style="white-
25f70 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a space:nowrap"> .
25f80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
25f90 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 :///C:/Documents
25fa0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 %20and%20Setting
25fb0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 s/fred/Desktop/d
25fc0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 ata.db.** <t
25fd0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a d> Windows only:
25fe0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
25ff0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 data.db" on fred
26000 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 's desktop on dr
26010 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
26020 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 C:. Note that th
26030 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 e %20 escaping i
26040 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 n this example i
26050 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a s not strictly .
26060 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 ** nece
26070 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 ssary - space ch
26080 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 aracters can be
26090 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a used literally.*
260a0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 * in UR
260b0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 I filenames..**
260c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
260d0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 ta.db?mode=ro&ca
260e0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e che=private <td>
260f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
26100 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 en file "data.db
26110 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
26120 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 directory for r
26130 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e ead-only access.
26140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 .** Reg
26150 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
26160 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
26170 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 -cache mode is e
26180 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 nabled by.**
26190 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 default, u
261a0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 se a private cac
261b0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 he..** <tr><td>
261c0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
261d0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 data.db?vfs=unix
261e0 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 -nolock <td>.**
261f0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
26200 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
26210 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 ata.db". Use the
26220 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e special VFS "un
26230 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c ix-nolock"..** <
26240 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
26250 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e a.db?mode=readon
26260 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 ly <td> .**
26270 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
26280 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 readonly" is not
26290 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 a valid option
262a0 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 for the "mode" p
262b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 arameter..** </t
262c0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 able>.**.** ^URI
262d0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
262e0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 ape sequences (%
262f0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 HH) are supporte
26300 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 d within the pat
26310 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 h and.** query c
26320 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 omponents of a U
26330 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 RI. A hexadecima
26340 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
26350 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a e consists of a.
26360 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 ** percent sign
26370 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 - "%" - followed
26380 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 by exactly two
26390 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 hexadecimal digi
263a0 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e ts .** specifyin
263b0 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 g an octet value
263c0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 . ^Before the pa
263d0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 th or query comp
263e0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 onents of a.** U
263f0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 RI filename are
26400 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 interpreted, the
26410 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 y are encoded us
26420 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c ing UTF-8 and al
26430 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 l .** hexadecima
26440 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
26450 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 es replaced by a
26460 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e single byte con
26470 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 taining the.** c
26480 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 orresponding oct
26490 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 et. If this proc
264a0 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e ess generates an
264b0 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 invalid UTF-8 e
264c0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 ncoding,.** the
264d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
264e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e fined..**.** <b>
264f0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
26500 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
26510 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
26520 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 r the filename a
26530 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 rgument.** of sq
26540 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
26550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26560 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 () must be UTF-8
26570 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a , not whatever.*
26580 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 * codepage is cu
26590 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e rrently defined.
265a0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 Filenames cont
265b0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 aining internati
265c0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 onal.** characte
265d0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 rs must be conve
265e0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 rted to UTF-8 pr
265f0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 ior to passing t
26600 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 hem into.** sqli
26610 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
26620 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
26630 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
26640 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d o Windows Runtim
26650 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 e users:</b> Th
26660 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 e temporary dire
26670 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 ctory must be se
26680 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 t.** prior to ca
26690 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 lling sqlite3_op
266a0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
266b0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 open_v2(). Othe
266c0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a rwise, various.*
266d0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 * features that
266e0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 require the use
266f0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c of temporary fil
26700 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a es may fail..**.
26710 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
26720 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 lite3_temp_direc
26730 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f tory].*/.SQLITE_
26740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
26750 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
26760 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
26770 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
26780 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
26790 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
267a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
267b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
267c0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f le */.);.SQLITE_
267d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
267e0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 open16(. const
267f0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 void *filename,
26800 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
26810 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 lename (UTF-16)
26820 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
26830 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
26840 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
26850 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 andle */.);.SQLI
26860 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
26870 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
26880 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
26890 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
268a0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
268b0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
268c0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
268d0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
268e0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
268f0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
26900 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
26910 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
26920 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
26930 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
26940 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
26950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26960 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f Obtain Values Fo
26970 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 r URI Parameters
26980 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
26990 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 utility routine
269a0 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 s, useful to VFS
269b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
269c0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 , that check.**
269d0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 to see if a data
269e0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 base file was a
269f0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e URI that contain
26a00 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 ed a specific qu
26a10 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ery .** paramete
26a20 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 r, and if so obt
26a30 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f ains the value o
26a40 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 f that query par
26a50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
26a60 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 F is the databa
26a70 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e se filename poin
26a80 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ter passed into
26a90 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 the xOpen() meth
26aa0 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 od of .** a VFS
26ab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
26ac0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 hen the flags pa
26ad0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
26ae0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a () has one or .*
26af0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 * more of the [S
26b00 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
26b10 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
26b20 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 MAIN_DB] bits se
26b30 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 t and.** P is th
26b40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 e name of the qu
26b50 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ery parameter, t
26b60 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 hen.** sqlite3_u
26b70 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
26b80 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 ) returns the va
26b90 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 lue of the P.**
26ba0 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 parameter if it
26bb0 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c exists or a NULL
26bc0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f pointer if P do
26bd0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 es not appear as
26be0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 a .** query par
26bf0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 ameter on F. If
26c00 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 P is a query pa
26c10 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 rameter of F.**
26c20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 has no explicit
26c30 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 value, then sqli
26c40 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
26c50 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a r(F,P) returns.*
26c60 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
26c70 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a n empty string..
26c80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26c90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
26ca0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 P,B) routine ass
26cb0 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 umes that P is a
26cc0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 boolean.** para
26cd0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
26ce0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 s true (1) or fa
26cf0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e lse (0) accordin
26d00 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a g to the value.*
26d10 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c * of P. The sql
26d20 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
26d30 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
26d40 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
26d50 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 if the.** value
26d60 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 of query parame
26d70 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
26d80 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f "yes", "true", o
26d90 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a r "on" in any.**
26da0 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 case or if the
26db0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 value begins wit
26dc0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d h a non-zero num
26dd0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 ber. The .** sq
26de0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
26df0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
26e00 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 s returns false
26e10 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 (0) if the value
26e20 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 of.** query par
26e30 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
26e40 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 of "no", "false"
26e50 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e , or "off" in an
26e60 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 y case or.** if
26e70 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
26e80 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 with a numeric
26e90 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e zero. If P is n
26ea0 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 ot a query.** pa
26eb0 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 rameter on F or
26ec0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 if the value of
26ed0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 P is does not ma
26ee0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a tch any of the.*
26ef0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 * above, then sq
26f00 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
26f10 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
26f20 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 (B!=0)..**.** T
26f30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 he sqlite3_uri_i
26f40 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 nt64(F,P,D) rout
26f50 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ine converts the
26f60 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f value of P into
26f70 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 a.** 64-bit sig
26f80 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
26f90 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 returns that int
26fa0 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 eger, or D if P
26fb0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 does not.** exis
26fc0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 t. If the value
26fd0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 of P is somethi
26fe0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e ng other than an
26ff0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a integer, then.*
27000 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e * zero is return
27010 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 ed..** .** If F
27020 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
27030 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
27040 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
27050 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 P) returns NULL
27060 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 and.** sqlite3_u
27070 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
27080 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 ) returns B. If
27090 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c F is not a NULL
270a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 pointer and.**
270b0 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
270c0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 e file pathname
270d0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c pointer that SQL
270e0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ite passed into
270f0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 the xOpen.** VFS
27100 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
27110 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
27120 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e is routine is un
27130 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
27140 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 ably.** undesira
27150 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ble..*/.SQLITE_A
27160 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
27170 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
27180 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 eter(const char
27190 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 *zFilename, cons
271a0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b t char *zParam);
271b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
271c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
271d0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ean(const char *
271e0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 zFile, const cha
271f0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 r *zParam, int b
27200 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 Default);.SQLITE
27210 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
27220 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 64 sqlite3_uri_i
27230 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a nt64(const char*
27240 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
27250 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a qlite3_int64);..
27260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27270 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
27280 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 Messages.**.**
27290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 ^The sqlite3_err
272a0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
272b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
272c0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
272d0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
272e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
272f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
27300 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 ent failed sqlit
27310 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a e3_* API call.**
27320 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
27330 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
27340 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 nection]. If a p
27350 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
27360 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 iled.** but the
27370 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
27380 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
27390 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
273a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
273b0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
273c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 defined. ^The s
273d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
273e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 errcode().** int
273f0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 erface is the sa
27400 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 me except that i
27410 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 t always returns
27420 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 the .** [extend
27430 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
27440 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 even when extend
27450 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
27460 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e are.** disabled.
27470 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
27480 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 te3_errmsg() and
27490 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 sqlite3_errmsg1
274a0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 6() return Engli
274b0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 sh-language.** t
274c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 ext that describ
274d0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 es the error, as
274e0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 either UTF-8 or
274f0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 UTF-16 respecti
27500 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 vely..** ^(Memor
27510 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 y to hold the er
27520 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
27530 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e ng is managed in
27540 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 ternally..** The
27550 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
27560 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f s not need to wo
27570 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e rry about freein
27580 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a g the result..**
27590 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 However, the er
275a0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 ror string might
275b0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 be overwritten
275c0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 or deallocated b
275d0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 y.** subsequent
275e0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 calls to other S
275f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 QLite interface
27600 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a functions.)^.**.
27610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
27620 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 errstr() interfa
27630 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 ce returns the E
27640 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 nglish-language
27650 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 text.** that des
27660 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 cribes the [resu
27670 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 lt code], as UTF
27680 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 -8..** ^(Memory
27690 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f to hold the erro
276a0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
276b0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 is managed inte
276c0 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 rnally.** and mu
276d0 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 st not be freed
276e0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
276f0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e on)^..**.** When
27700 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 the serialized
27710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
27720 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d is in use, it m
27730 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 ight be the.** c
27740 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e ase that a secon
27750 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f d error occurs o
27760 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 n a separate thr
27770 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a ead in between.*
27780 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 * the time of th
27790 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e e first error an
277a0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 d the call to th
277b0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a ese interfaces..
277c0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 ** When that hap
277d0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 pens, the second
277e0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 error will be r
277f0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 eported since th
27800 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ese.** interface
27810 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 s always report
27820 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
27830 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 result. To avoi
27840 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 d.** this, each
27850 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 thread can obtai
27860 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 n exclusive use
27870 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
27880 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a connection] D.*
27890 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 * by invoking [s
278a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 qlite3_mutex_ent
278b0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f er]([sqlite3_db_
278c0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 mutex](D)) befor
278d0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 e beginning.** t
278e0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f o use D and invo
278f0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
27900 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 tex_leave]([sqli
27910 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
27920 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 ) after.** all c
27930 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 alls to the inte
27940 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 rfaces listed he
27950 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 re are completed
27960 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ..**.** If an in
27970 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
27980 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 th SQLITE_MISUSE
27990 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
279a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 interface.** wa
279b0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 s invoked incorr
279c0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 ectly by the app
279d0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 lication. In th
279e0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 at case, the.**
279f0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
27a00 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 essage may or ma
27a10 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f y not be set..*/
27a20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
27a30 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
27a40 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 sqlite3 *db);.SQ
27a50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
27a60 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
27a70 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
27a80 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 b);.SQLITE_API c
27a90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
27aa0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 e3_errmsg(sqlite
27ab0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 3*);.SQLITE_API
27ac0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
27ad0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
27ae0 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
27af0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
27b00 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e qlite3_errstr(in
27b10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
27b20 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 REF: SQL Stateme
27b30 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 nt Object.** KEY
27b40 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 WORDS: {prepared
27b50 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 statement} {pre
27b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
27b70 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 }.**.** An insta
27b80 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
27b90 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 ct represents a
27ba0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 single SQL state
27bb0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ment..** This ob
27bc0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c ject is variousl
27bd0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 y known as a "pr
27be0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27bf0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 " or a.** "compi
27c00 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e led SQL statemen
27c10 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 t" or simply as
27c20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a a "statement"..*
27c30 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 *.** The life of
27c40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a a statement obj
27c50 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 ect goes somethi
27c60 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ng like this:.**
27c70 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
27c80 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 Create the obje
27c90 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
27ca0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
27cb0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 or a related.**
27cc0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a function..*
27cd0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 * <li> Bind valu
27ce0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 es to [host para
27cf0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 meters] using th
27d00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
27d10 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 ().** inter
27d20 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 faces..** <li> R
27d30 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
27d40 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
27d50 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
27d60 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
27d70 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 > Reset the stat
27d80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
27d90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
27da0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
27db0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
27dc0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
27dd0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
27de0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
27df0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
27e00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
27e10 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
27e20 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 Refer to docume
27e30 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 ntation on indiv
27e40 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 idual methods ab
27e50 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ove for addition
27e60 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
27e70 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
27e80 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d ruct sqlite3_stm
27e90 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a t sqlite3_stmt;.
27ea0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27eb0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 Run-time Limits
27ec0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e .**.** ^(This in
27ed0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 terface allows t
27ee0 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f he size of vario
27ef0 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f us constructs to
27f00 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f be limited.** o
27f10 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 n a connection b
27f20 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 y connection bas
27f30 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 is. The first p
27f40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
27f50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
27f60 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c nection] whose l
27f70 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 imit is to be se
27f80 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 t or queried. T
27f90 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
27fa0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 ameter is one of
27fb0 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 the [limit cate
27fc0 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 gories] that def
27fd0 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f ine a.** class o
27fe0 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 f constructs to
27ff0 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e be size limited.
28000 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 The third para
28010 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
28020 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 new limit for th
28030 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a at construct.)^.
28040 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 **.** ^If the ne
28050 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 w limit is a neg
28060 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 ative number, th
28070 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 e limit is uncha
28080 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 nged..** ^(For e
28090 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ach limit catego
280a0 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ry SQLITE_LIMIT_
280b0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 <i>NAME</i> ther
280c0 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 e is a .** [limi
280d0 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 ts | hard upper
280e0 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 bound].** set at
280f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 compile-time by
28100 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f a C preprocesso
28110 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a r macro called.*
28120 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 * [limits | SQLI
28130 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f TE_MAX_<i>NAME</
28140 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c i>]..** (The "_L
28150 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 IMIT_" in the na
28160 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f me is changed to
28170 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 "_MAX_".))^.**
28180 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 ^Attempts to inc
28190 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 rease a limit ab
281a0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 ove its hard upp
281b0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 er bound are.**
281c0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
281d0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 ed to the hard u
281e0 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a pper bound..**.*
281f0 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 * ^Regardless of
28200 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
28210 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 the limit was ch
28220 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b anged, the .** [
28230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
28240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
28250 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ns the prior val
28260 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e ue of the limit.
28270 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 .** ^Hence, to f
28280 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 ind the current
28290 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 value of a limit
282a0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e without changin
282b0 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 g it,.** simply
282c0 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 invoke this inte
282d0 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 rface with the t
282e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 hird parameter s
282f0 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 et to -1..**.**
28300 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 Run-time limits
28310 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 are intended for
28320 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 use in applicat
28330 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 ions that manage
28340 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f .** both their o
28350 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 wn internal data
28360 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 base and also da
28370 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 tabases that are
28380 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 controlled.** b
28390 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 y untrusted exte
283a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 rnal sources. A
283b0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 n example applic
283c0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 ation might be a
283d0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 .** web browser
283e0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e that has its own
283f0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 databases for s
28400 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 toring history a
28410 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 nd.** separate d
28420 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c atabases control
28430 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 led by JavaScrip
28440 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 t applications d
28450 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 ownloaded.** off
28460 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 the Internet.
28470 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 The internal dat
28480 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 abases can be gi
28490 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 ven the.** large
284a0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 , default limits
284b0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e . Databases man
284c0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c aged by external
284d0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 sources can.**
284e0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d be given much sm
284f0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 aller limits des
28500 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 igned to prevent
28510 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 a denial of ser
28520 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 vice.** attack.
28530 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 Developers migh
28540 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 t also want to u
28550 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
28560 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
28570 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 ].** interface t
28580 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f o further contro
28590 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e l untrusted SQL.
285a0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
285b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 e database.** cr
285c0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 eated by an untr
285d0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e usted script can
285e0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 be contained us
285f0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f ing the.** [max_
28600 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
28610 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 GMA]..**.** New
28620 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 run-time limit c
28630 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 ategories may be
28640 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
28650 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 releases..*/.SQ
28660 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
28670 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 ite3_limit(sqlit
28680 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 e3*, int id, int
28690 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a newVal);../*.**
286a0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
286b0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f ime Limit Catego
286c0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ries.** KEYWORDS
286d0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 : {limit categor
286e0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 y} {*limit categ
286f0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 ories}.**.** The
28700 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 se constants def
28710 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 ine various perf
28720 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a ormance limits.*
28730 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f * that can be lo
28740 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d wered at run-tim
28750 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
28760 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 _limit()]..** Th
28770 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 e synopsis of th
28780 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 e meanings of th
28790 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 e various limits
287a0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e is shown below.
287b0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 .** Additional i
287c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 nformation is av
287d0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 ailable at [limi
287e0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 ts | Limits in S
287f0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 QLite]..**.** <d
28800 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c l>.** [[SQLITE_L
28810 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 IMIT_LENGTH]] ^(
28820 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28830 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
28840 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
28850 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 size of any stri
28860 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 ng or BLOB or ta
28870 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 ble row, in byte
28880 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b s.<dd>)^.**.** [
28890 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 [SQLITE_LIMIT_SQ
288a0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 L_LENGTH]] ^(<dt
288b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 >SQLITE_LIMIT_SQ
288c0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a L_LENGTH</dt>.**
288d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
288e0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 length of an SQ
288f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 L statement, in
28900 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a bytes.</dd>)^.**
28910 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
28920 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 IT_COLUMN]] ^(<d
28930 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
28940 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 OLUMN</dt>.** <d
28950 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
28960 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
28970 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e in a table defin
28980 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a ition or in the.
28990 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ** result set of
289a0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 a [SELECT] or t
289b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
289c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
289d0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 an index.** or i
289e0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 n an ORDER BY or
289f0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 GROUP BY clause
28a00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
28a10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 [SQLITE_LIMIT_EX
28a20 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 PR_DEPTH]] ^(<dt
28a30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 >SQLITE_LIMIT_EX
28a40 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a PR_DEPTH</dt>.**
28a50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28a60 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 depth of the pa
28a70 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 rse tree on any
28a80 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e expression.</dd>
28a90 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
28aa0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
28ab0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e _SELECT]] ^(<dt>
28ac0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
28ad0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 POUND_SELECT</dt
28ae0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28af0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
28b00 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 erms in a compou
28b10 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d nd SELECT statem
28b20 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ent.</dd>)^.**.*
28b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
28b40 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 _VDBE_OP]] ^(<dt
28b50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 >SQLITE_LIMIT_VD
28b60 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 BE_OP</dt>.** <d
28b70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
28b80 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 mber of instruct
28b90 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 ions in a virtua
28ba0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 l machine progra
28bb0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 m.** used to imp
28bc0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 lement an SQL st
28bd0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c atement. This l
28be0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 imit is not curr
28bf0 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 ently.** enforce
28c00 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d d, though that m
28c10 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e ight be added in
28c20 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
28c30 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
28c40 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
28c50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 [[SQLITE_LIMIT_F
28c60 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 UNCTION_ARG]] ^(
28c70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28c80 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 _FUNCTION_ARG</d
28c90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
28ca0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
28cb0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 arguments on a f
28cc0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a unction.</dd>)^.
28cd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
28ce0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 IMIT_ATTACHED]]
28cf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
28d00 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e IT_ATTACHED</dt>
28d10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
28d20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 mum number of [A
28d30 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 TTACH | attached
28d40 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f databases].)^</
28d50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
28d60 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
28d70 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a TTERN_LENGTH]].*
28d80 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
28d90 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
28da0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a N_LENGTH</dt>.**
28db0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
28dc0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 length of the p
28dd0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 attern argument
28de0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 to the [LIKE] or
28df0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 .** [GLOB] opera
28e00 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tors.</dd>)^.**.
28e10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
28e20 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
28e30 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c R]].** ^(<dt>SQL
28e40 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
28e50 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a LE_NUMBER</dt>.*
28e60 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
28e70 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f m index number o
28e80 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 f any [parameter
28e90 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 ] in an SQL stat
28ea0 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b ement.)^.**.** [
28eb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 [SQLITE_LIMIT_TR
28ec0 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 IGGER_DEPTH]] ^(
28ed0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28ee0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f _TRIGGER_DEPTH</
28ef0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
28f00 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
28f10 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 recursion for tr
28f20 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a iggers.</dd>)^.*
28f30 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
28f40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
28f50 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
28f60 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
28f70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
28f80 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 _SQL_LENGTH
28f90 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
28fa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
28fb0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 T_COLUMN
28fc0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 2.#d
28fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
28fe0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 IT_EXPR_DEPTH
28ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 3.#
29000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
29010 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
29020 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a ECT 4.
29030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
29040 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 IMIT_VDBE_OP
29050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
29060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29070 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
29080 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RG
29090 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
290a0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 _LIMIT_ATTACHED
290b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
290c0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
290d0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
290e0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 TERN_LENGTH
290f0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
29100 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
29110 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 E_NUMBER
29120 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 9.#define SQL
29130 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
29140 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
29150 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 10../*.** CAP
29160 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
29170 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
29180 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
29190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
291a0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f mpiler}.**.** To
291b0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
291c0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 query, it must f
291d0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 irst be compiled
291e0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 into a byte-cod
291f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 e.** program usi
29200 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 ng one of these
29210 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
29220 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
29230 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
29240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29250 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
29260 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 om a.** prior su
29270 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
29280 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
29290 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
292a0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
292b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
292c0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 The database c
292d0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
292e0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f ot have been clo
292f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 sed..**.** The s
29300 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 econd argument,
29310 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 "zSql", is the s
29320 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
29330 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 ompiled, encoded
29340 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 .** as either UT
29350 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 F-8 or UTF-16.
29360 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
29370 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 are() and sqlite
29380 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 3_prepare_v2().*
29390 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 * interfaces use
293a0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 UTF-8, and sqli
293b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 te3_prepare16()
293c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
293d0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 are16_v2().** us
293e0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
293f0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 ^If the nByte ar
29400 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 gument is less t
29410 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a han zero, then z
29420 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
29430 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
29440 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
29450 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e ^If nByte is non
29460 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
29470 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 it is the maximu
29480 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 m.** number of
29490 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 bytes read from
294a0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 zSql. ^When nBy
294b0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
294c0 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 ve, the.** zSql
294d0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 string ends at e
294e0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 ither the first
294f0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 '\000' or '\u000
29500 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 0' character or.
29510 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 ** the nByte-th
29520 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 byte, whichever
29530 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 comes first. If
29540 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 the caller knows
29550 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 .** that the sup
29560 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 plied string is
29570 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 nul-terminated,
29580 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 then there is a
29590 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d small.** perform
295a0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 ance advantage t
295b0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 o be gained by p
295c0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 assing an nByte
295d0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a parameter that.*
295e0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 * is equal to th
295f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
29600 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 s in the input s
29610 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 tring <i>includi
29620 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 ng</i>.** the nu
29630 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 l-terminator byt
29640 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 es as this saves
29650 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 SQLite from hav
29660 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 ing to.** make a
29670 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 copy of the inp
29680 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ut string..**.**
29690 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e ^If pzTail is n
296a0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a ot NULL then *pz
296b0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 Tail is made to
296c0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 point to the fir
296d0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 st byte.** past
296e0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
296f0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 irst SQL stateme
29700 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 nt in zSql. The
29710 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 se routines only
29720 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 .** compile the
29730 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 first statement
29740 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 in zSql, so *pzT
29750 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e ail is left poin
29760 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 ting to.** what
29770 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c remains uncompil
29780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 ed..**.** ^*ppSt
29790 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 mt is left point
297a0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 ing to a compile
297b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
297c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 ement] that can
297d0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 be.** executed u
297e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 sing [sqlite3_st
297f0 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 ep()]. ^If ther
29800 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a e is an error, *
29810 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a ppStmt is set.**
29820 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 to NULL. ^If t
29830 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
29840 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
29850 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 f the input is a
29860 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e n empty.** strin
29870 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 g or a comment)
29880 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 then *ppStmt is
29890 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 set to NULL..**
298a0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 The calling proc
298b0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 edure is respons
298c0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e ible for deletin
298d0 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a g the compiled.*
298e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
298f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
29900 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 inalize()] after
29910 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
29920 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 with it..** ppS
29930 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e tmt may not be N
29940 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 ULL..**.** ^On s
29950 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 uccess, the sqli
29960 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 te3_prepare() fa
29970 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 mily of routines
29980 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
29990 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 OK];.** otherwis
299a0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
299b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
299c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
299d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e _prepare_v2() an
299e0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
299f0 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 e16_v2() interfa
29a00 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d ces are.** recom
29a10 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e mended for all n
29a20 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 ew programs. The
29a30 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 two older inter
29a40 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e faces are retain
29a50 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 ed.** for backwa
29a60 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
29a70 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 y, but their use
29a80 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e is discouraged.
29a90 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 .** ^In the "v2"
29aa0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
29ab0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
29ac0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 ent.** that is r
29ad0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 eturned (the [sq
29ae0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
29af0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 ct) contains a c
29b00 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 opy of the.** or
29b10 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e iginal SQL text.
29b20 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 This causes the
29b30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
29b40 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a ] interface to.*
29b50 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 * behave differe
29b60 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 ntly in three wa
29b70 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a ys:.**.** <ol>.*
29b80 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
29b90 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
29ba0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 a changes, inste
29bb0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 ad of returning
29bc0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 [SQLITE_SCHEMA]
29bd0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 as it.** always
29be0 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c used to do, [sql
29bf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
29c00 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
29c10 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 recompile the SQ
29c20 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 L.** statement a
29c30 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 nd try to run it
29c40 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e again..** </li>
29c50 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
29c60 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
29c70 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 curs, [sqlite3_s
29c80 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 tep()] will retu
29c90 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 rn one of the de
29ca0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 tailed.** [error
29cb0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
29cc0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
29cd0 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 ]. ^The legacy
29ce0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 behavior was tha
29cf0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 t.** [sqlite3_st
29d00 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 ep()] would only
29d10 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 return a generi
29d20 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d c [SQLITE_ERROR]
29d30 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 result code.**
29d40 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
29d50 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 ion would have t
29d60 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
29d70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
29d80 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 _reset()].** in
29d90 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
29da0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
29db0 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
29dc0 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 m. With the "v2"
29dd0 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 prepare.** inte
29de0 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
29df0 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
29e00 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 r the error is r
29e10 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 eturned immediat
29e20 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ely..** </li>.**
29e30 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
29e40 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c the specific val
29e50 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 ue bound to [par
29e60 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 ameter | host pa
29e70 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
29e80 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 .** WHERE clause
29e90 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
29ea0 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 the choice of q
29eb0 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 uery plan for a
29ec0 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 statement,.** th
29ed0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 en the statement
29ee0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 will be automat
29ef0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
29f00 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 d, as if there h
29f10 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 ad been .** a sc
29f20 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 hema change, on
29f30 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 the first [sqli
29f40 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
29f50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 following any c
29f60 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 hange.** to the
29f70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
29f80 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f xt | bindings] o
29f90 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 f that [paramete
29fa0 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 r]. .** ^The spe
29fb0 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 cific value of W
29fc0 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 HERE-clause [par
29fd0 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e ameter] might in
29fe0 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 fluence the .**
29ff0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2a000 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 plan if the para
2a010 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 meter is the lef
2a020 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 t-hand side of a
2a030 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 [LIKE].** or [G
2a040 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 LOB] operator or
2a050 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2a060 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f r is compared to
2a070 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 an indexed colu
2a080 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 mn.** and the [S
2a090 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 QLITE_ENABLE_STA
2a0a0 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 T3] compile-time
2a0b0 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
2a0c0 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c ed..** the .** <
2a0d0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f /li>.** </ol>.*/
2a0e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a0f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2a100 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2a110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2a120 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2a130 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2a140 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2a150 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2a160 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 -8 encoded */.
2a170 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2a180 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2a190 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2a1a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2a1b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2a1c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2a1d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2a1e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
2a1f0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f r **pzTail /
2a200 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2a210 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2a220 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 of zSql */.);.S
2a230 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2a240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2a250 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2a260 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2a270 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2a280 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2a290 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2a2a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2a2b0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
2a2c0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
2a2d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
2a2e0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
2a2f0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
2a300 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
2a310 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
2a320 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
2a330 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2a340 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
2a350 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
2a360 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
2a370 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
2a380 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2a390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a3a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2a3b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2a3c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2a3d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2a3e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2a3f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2a400 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
2a410 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2a420 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2a430 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2a440 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2a450 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2a460 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2a470 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2a480 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2a490 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
2a4a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2a4b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2a4c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2a4d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2a4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a4f0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
2a500 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2a510 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
2a520 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2a530 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
2a540 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
2a550 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
2a560 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2a570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2a580 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2a590 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2a5a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2a5b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2a5c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2a5d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a5e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
2a5f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2a600 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2a610 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2a620 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
2a630 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 3REF: Retrieving
2a640 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a Statement SQL.*
2a650 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 *.** ^This inter
2a660 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
2a670 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 to retrieve a s
2a680 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 aved copy of the
2a690 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c original.** SQL
2a6a0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 text used to cr
2a6b0 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 eate a [prepared
2a6c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 statement] if t
2a6d0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 hat statement wa
2a6e0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 s.** compiled us
2a6f0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 ing either [sqli
2a700 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2a710 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
2a720 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2a730 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2a740 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2a750 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
2a760 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2a770 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
2a780 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
2a790 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 Statement Writes
2a7a0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a The Database.**
2a7b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2a7c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 _stmt_readonly(X
2a7d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2a7e0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 rns true (non-ze
2a7f0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e ro) if.** and on
2a800 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 ly if the [prepa
2a810 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 red statement] X
2a820 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 makes no direct
2a830 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 changes to.** t
2a840 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
2a850 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
2a860 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
2a870 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
2a880 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2a890 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 ons] or.** [virt
2a8a0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 ual tables] migh
2a8b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 t change the dat
2a8c0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 abase indirectly
2a8d0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 as a side effec
2a8e0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 t. .** ^(For ex
2a8f0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 ample, if an app
2a900 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 lication defines
2a910 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 a function "eva
2a920 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 l()" that .** ca
2a930 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 lls [sqlite3_exe
2a940 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 c()], then the f
2a950 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 ollowing SQL sta
2a960 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 tement would.**
2a970 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
2a980 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 ase file through
2a990 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a side-effects:.*
2a9a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
2a9b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c ><pre>.** SEL
2a9c0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 ECT eval('DELETE
2a9d0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 FROM t1') FROM
2a9e0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 t2;.** </pre></b
2a9f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
2aa00 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 But because the
2aa10 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2aa20 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ent does not cha
2aa30 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nge the database
2aa40 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c file.** directl
2aa50 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f y, sqlite3_stmt_
2aa60 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 readonly() would
2aa70 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 still return tr
2aa80 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 ue.)^.**.** ^Tra
2aa90 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
2aaa0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 statements such
2aab0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f as [BEGIN], [CO
2aac0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b MMIT], [ROLLBACK
2aad0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 ],.** [SAVEPOINT
2aae0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d ], and [RELEASE]
2aaf0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 cause sqlite3_s
2ab00 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 tmt_readonly() t
2ab10 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a o return true,.*
2ab20 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 * since the stat
2ab30 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 ements themselve
2ab40 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c s do not actuall
2ab50 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 y modify the dat
2ab60 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 abase but.** rat
2ab70 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c her they control
2ab80 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 the timing of w
2ab90 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d hen other statem
2aba0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 ents modify the
2abb0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e .** database. ^
2abc0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 The [ATTACH] and
2abd0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d [DETACH] statem
2abe0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a ents also cause.
2abf0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f ** sqlite3_stmt_
2ac00 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
2ac10 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c turn true since,
2ac20 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 while those sta
2ac30 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 tements.** chang
2ac40 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 e the configurat
2ac50 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 ion of a databas
2ac60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 e connection, th
2ac70 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a ey do not make .
2ac80 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ** changes to th
2ac90 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2aca0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 database files
2acb0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 on disk..*/.SQLI
2acc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2acd0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2ace0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2acf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2ad00 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
2ad10 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 e If A Prepared
2ad20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 Statement Has Be
2ad30 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e en Reset.**.** ^
2ad40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 The sqlite3_stmt
2ad50 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 _busy(S) interfa
2ad60 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
2ad70 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 (non-zero) if th
2ad80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2ad90 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 tatement] S has
2ada0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 been stepped at
2adb0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 least once using
2adc0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
2add0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e ep(S)] but has n
2ade0 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 ot run to comple
2adf0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 tion and/or has
2ae00 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 not .** been res
2ae10 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 et using [sqlite
2ae20 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 3_reset(S)]. ^T
2ae30 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
2ae40 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 busy(S).** inter
2ae50 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c face returns fal
2ae60 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c se if S is a NUL
2ae70 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 L pointer. If S
2ae80 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 is not a .** NU
2ae90 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 LL pointer and i
2aea0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 s not a pointer
2aeb0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 to a valid [prep
2aec0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2aed0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 ** object, then
2aee0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
2aef0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2af00 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 obably undesirab
2af10 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 le..**.** This i
2af20 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
2af30 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 used in combinat
2af40 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 ion [sqlite3_nex
2af50 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 t_stmt()].** to
2af60 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 locate all prepa
2af70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 red statements a
2af80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
2af90 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f database .** co
2afa0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 nnection that ar
2afb0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 e in need of bei
2afc0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 ng reset. This
2afd0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 can be used,.**
2afe0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 for example, in
2aff0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 diagnostic routi
2b000 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f nes to search fo
2b010 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 r prepared .** s
2b020 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 tatements that a
2b030 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 re holding a tra
2b040 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a nsaction open..*
2b050 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2b060 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2b070 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a sy(sqlite3_stmt*
2b080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b090 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
2b0a0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
2b0b0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
2b0c0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
2b0d0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
2b0e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2b0f0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
2b100 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
2b110 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2b120 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
2b130 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
2b140 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
2b150 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
2b160 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
2b170 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
2b180 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
2b190 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 it stores. ^Va
2b1a0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
2b1b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2b1c0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
2b1d0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
2b1e0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
2b1f0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
2b200 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
2b210 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
2b220 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
2b230 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
2b240 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
2b250 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
2b260 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
2b270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b280 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
2b290 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
2b2a0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
2b2b0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
2b2c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
2b2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
2b2e0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
2b2f0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
2b300 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
2b310 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
2b320 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
2b330 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
2b340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b350 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 3_value..**.** T
2b360 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 he terms "protec
2b370 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 ted" and "unprot
2b380 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 ected" refer to
2b390 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a whether or not.*
2b3a0 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c * a mutex is hel
2b3b0 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 d. An internal
2b3c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
2b3d0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a r a protected.**
2b3e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2b3f0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 bject but no mut
2b400 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
2b410 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a n unprotected.**
2b420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2b430 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 bject. If SQLit
2b440 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f e is compiled to
2b450 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 be single-threa
2b460 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 ded.** (with [SQ
2b470 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
2b480 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 0] and with [sql
2b490 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
2b4a0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a )] returning 0).
2b4b0 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 ** or if SQLite
2b4c0 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 is run in one of
2b4d0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d reduced mutex m
2b4e0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 odes .** [SQLITE
2b4f0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
2b500 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 READ] or [SQLITE
2b510 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
2b520 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 EAD].** then the
2b530 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 re is no distinc
2b540 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
2b550 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
2b560 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
2b570 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
2b580 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 and they can be
2b590 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 used interchange
2b5a0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a ably. However,.
2b5b0 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 ** for maximum c
2b5c0 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 ode portability
2b5d0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
2b5e0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
2b5f0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b ons.** still mak
2b600 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f e the distinctio
2b610 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
2b620 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
2b630 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
2b640 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
2b650 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
2b660 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
2b670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b680 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 _value objects t
2b690 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 hat are passed a
2b6a0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 s parameters int
2b6b0 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 o the.** impleme
2b6c0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c ntation of [appl
2b6d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2b6e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 SQL functions] a
2b6f0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a re protected..**
2b700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
2b710 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 lue object retur
2b720 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
2b730 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2b740 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 )] is unprotecte
2b750 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 d..** Unprotecte
2b760 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
2b770 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 objects may only
2b780 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a be used with.**
2b790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2b7a0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
2b7b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2b7c0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
2b7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
2b7e0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 | sqlite3_value
2b7f0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 _type()] family
2b800 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
2b810 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 require protect
2b820 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2b830 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 objects..*/.typ
2b840 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 edef struct Mem
2b850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a sqlite3_value;..
2b860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2b870 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e SQL Function Con
2b880 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a text Object.**.*
2b890 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
2b8a0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
2b8b0 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
2b8c0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
2b8d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
2b8e0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 xt object. ^A p
2b8f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
2b900 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
2b910 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ect.** is always
2b920 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
2b930 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e to [application
2b940 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
2b950 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 ctions]..** The
2b960 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2b970 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2b980 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2b990 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a will pass this.*
2b9a0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 * pointer throug
2b9b0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 h into calls to
2b9c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
2b9d0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 int | sqlite3_re
2b9e0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sult()],.** [sql
2b9f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
2ba00 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 ontext()], [sqli
2ba10 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
2ba20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f ,.** [sqlite3_co
2ba30 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
2ba40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 )], [sqlite3_get
2ba50 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 _auxdata()],.**
2ba60 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f and/or [sqlite3_
2ba70 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a set_auxdata()]..
2ba80 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
2ba90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
2baa0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
2bab0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
2bac0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 EF: Binding Valu
2bad0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 es To Prepared S
2bae0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 tatements.** KEY
2baf0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
2bb00 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
2bb10 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
2bb20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
2bb30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
2bb40 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
2bb50 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
2bb60 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
2bb70 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 }.**.** ^(In the
2bb80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
2bb90 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
2bba0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2bbb0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
2bbc0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
2bbd0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
2bbe0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
2bbf0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
2bc00 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
2bc10 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
2bc20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2bc30 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
2bc40 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
2bc50 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
2bc60 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
2bc70 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
2bc80 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
2bc90 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
2bca0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
2bcb0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
2bcc0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
2bcd0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
2bce0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 ntifier.)^ ^The
2bcf0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
2bd00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
2bd10 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
2bd20 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2bd30 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
2bd40 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
2bd50 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
2bd60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2bd70 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
2bd80 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d here..**.** ^T
2bd90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2bda0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
2bdb0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2bdc0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 es is always.**
2bdd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2bde0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
2bdf0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2be00 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
2be10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2be20 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a r its variants..
2be30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
2be40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2be50 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
2be60 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
2be70 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 be set..** ^The
2be80 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
2be90 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
2bea0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e dex of 1. ^When
2beb0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
2bec0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
2bed0 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
2bee0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
2bef0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
2bf00 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
2bf10 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
2bf20 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
2bf30 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 ccurrence..** ^T
2bf40 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
2bf50 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
2bf60 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
2bf70 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
2bf80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2bf90 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
2bfa0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 if desired. ^T
2bfb0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
2bfc0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
2bfd0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
2bfe0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e f NNN..** ^The N
2bff0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
2c000 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
2c010 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
2c020 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
2c030 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
2c040 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
2c050 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
2c060 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 999)..**.** ^Th
2c070 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
2c080 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
2c090 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
2c0a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ameter..**.** ^(
2c0b0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
2c0c0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
2c0d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
2c0e0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
2c0f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
2c100 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
2c110 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
2c120 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
2c130 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2c140 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
2c150 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
2c160 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
2c170 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e aracters.)^.** ^
2c180 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2c190 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2c1a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f e3_bind_text() o
2c1b0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2c1c0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 ext16().** is ne
2c1d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
2c1e0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
2c1f0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
2c200 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2c210 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
2c220 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2c230 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
2c240 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2c250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c260 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 () is negative,
2c270 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 then.** the beha
2c280 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
2c290 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e d..** If a non-n
2c2a0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 egative fourth p
2c2b0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 arameter is prov
2c2c0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ided to sqlite3_
2c2d0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f bind_text().** o
2c2e0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2c2f0 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 ext16() then tha
2c300 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
2c310 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
2c320 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 set.** where the
2c330 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 NUL terminator
2c340 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 would occur assu
2c350 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 ming the string
2c360 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d were NUL.** term
2c370 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 inated. If any
2c380 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f NUL characters o
2c390 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 ccur at byte off
2c3a0 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a sets less than .
2c3b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ** the value of
2c3c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2c3d0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 eter then the re
2c3e0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 sulting string v
2c3f0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e alue will.** con
2c400 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
2c410 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 Ls. The result
2c420 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 of expressions i
2c430 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 nvolving strings
2c440 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 .** with embedde
2c450 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 d NULs is undefi
2c460 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2c470 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
2c480 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
2c490 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 lob(), sqlite3_b
2c4a0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a ind_text(), and.
2c4b0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ** sqlite3_bind_
2c4c0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 text16() is a de
2c4d0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
2c4e0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2c4f0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e BLOB or.** strin
2c500 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 g after SQLite h
2c510 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
2c520 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 it. ^The destr
2c530 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a uctor is called.
2c540 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ** to dispose of
2c550 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 the BLOB or str
2c560 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
2c570 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
2c580 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 bind_blob(),.**
2c590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2c5a0 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f t(), or sqlite3_
2c5b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 bind_text16() fa
2c5c0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 ils. .** ^If th
2c5d0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2c5e0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
2c5f0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
2c600 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
2c610 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
2c620 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
2c630 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
2c640 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
2c650 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
2c660 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
2c670 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 d..** ^If the fi
2c680 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
2c690 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 the value [SQLI
2c6a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 TE_TRANSIENT], t
2c6b0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 hen.** SQLite ma
2c6c0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 kes its own priv
2c6d0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
2c6e0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 data immediately
2c6f0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 , before.** the
2c700 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2c710 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2c720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2c730 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2c740 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
2c750 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
2c760 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
2c770 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
2c780 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f oes. ^A zeroblo
2c790 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
2c7a0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
2c7b0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
2c7c0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
2c7d0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
2c7e0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
2c7f0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
2c800 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
2c810 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
2c820 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
2c830 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
2c840 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
2c850 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
2c860 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
2c870 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
2c880 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
2c890 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 ** ^A negative v
2c8a0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 alue for the zer
2c8b0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e oblob results in
2c8c0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
2c8d0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 LOB..**.** ^If a
2c8e0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ny of the sqlite
2c8f0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2c900 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 nes are called w
2c910 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
2c920 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 er.** for the [p
2c930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c940 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 t] or with a pre
2c950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2c960 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 for which.** [sq
2c970 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2c980 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f s been called mo
2c990 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e re recently than
2c9a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c9b0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 )],.** then the
2c9c0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e call will return
2c9d0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2c9e0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 . If any sqlite
2c9f0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 3_bind_().** rou
2ca00 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 tine is passed a
2ca10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ca20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 ment] that has b
2ca30 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 een finalized, t
2ca40 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 he.** result is
2ca50 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
2ca60 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a obably harmful..
2ca70 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 **.** ^Bindings
2ca80 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
2ca90 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
2caa0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
2cab0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 ..** ^Unbound pa
2cac0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
2cad0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
2cae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2caf0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 ite3_bind_* rout
2cb00 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
2cb10 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
2cb20 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 ss or an.** [err
2cb30 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 or code] if anyt
2cb40 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
2cb50 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e .** ^[SQLITE_RAN
2cb60 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 GE] is returned
2cb70 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
2cb80 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 .** index is out
2cb90 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 of range. ^[SQ
2cba0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 LITE_NOMEM] is r
2cbb0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f eturned if mallo
2cbc0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a c() fails..**.**
2cbd0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2cbe0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2cbf0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 er_count()],.**
2cc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2cc10 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
2cc20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
2cc30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2cc40 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
2cc50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2cc60 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 _bind_blob(sqlit
2cc70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2cc80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
2cc90 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
2cca0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2ccb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2ccc0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
2ccd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
2cce0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 e);.SQLITE_API i
2ccf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2cd00 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
2cd10 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 *, int, int);.SQ
2cd20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2cd30 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
2cd40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2cd50 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
2cd60 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 4);.SQLITE_API i
2cd70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2cd80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
2cd90 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 t*, int);.SQLITE
2cda0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2cdb0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
2cdc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2cdd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
2cde0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
2cdf0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2ce00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2ce10 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2ce20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2ce30 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
2ce40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2ce50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2ce60 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
2ce70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2ce80 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
2ce90 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2cea0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2ceb0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
2cec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2ced0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a nt, int n);../*.
2cee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
2cef0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d ber Of SQL Param
2cf00 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 eters.**.** ^Thi
2cf10 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 s routine can be
2cf20 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 used to find th
2cf30 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c e number of [SQL
2cf40 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 parameters].**
2cf50 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 in a [prepared s
2cf60 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 tatement]. SQL
2cf70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 parameters are t
2cf80 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 okens of the.**
2cf90 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 form "?", "?NNN"
2cfa0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 , ":AAA", "$AAA"
2cfb0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 , or "@AAA" that
2cfc0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 serve as.** pla
2cfd0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 ceholders for va
2cfe0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 lues that are [s
2cff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2d000 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 | bound].** to
2d010 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 the parameters a
2d020 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a t a later time..
2d030 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 **.** ^(This rou
2d040 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 tine actually re
2d050 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 turns the index
2d060 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 of the largest (
2d070 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 rightmost).** pa
2d080 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c rameter. For all
2d090 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e forms except ?N
2d0a0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f NN, this will co
2d0b0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a rrespond to the.
2d0c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 ** number of uni
2d0d0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 que parameters.
2d0e0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f If parameters o
2d0f0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 f the ?NNN form
2d100 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 are used,.** the
2d110 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 re may be gaps i
2d120 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a n the list.)^.**
2d130 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2d140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2d150 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2d160 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2d180 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 e()], and.** [sq
2d190 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2d1a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
2d1b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2d1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2d1d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 rameter_count(sq
2d1e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2d1f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2d200 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 ame Of A Host Pa
2d210 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 rameter.**.** ^T
2d220 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2d230 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
2d240 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
2d250 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
2d260 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
2d270 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
2d280 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2d290 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
2d2a0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
2d2b0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
2d2c0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
2d2d0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
2d2e0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
2d2f0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
2d300 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
2d310 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
2d320 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
2d330 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
2d340 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2d350 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
2d360 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
2d370 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
2d380 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
2d390 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
2d3a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
2d3b0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
2d3c0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
2d3d0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
2d3e0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
2d3f0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
2d400 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
2d410 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
2d420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2d430 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
2d440 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2d450 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
2d460 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
2d470 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2d480 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
2d490 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
2d4a0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
2d4b0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
2d4c0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2d4d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
2d4e0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
2d4f0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
2d500 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
2d510 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
2d520 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
2d530 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
2d540 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
2d550 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2d560 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
2d570 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2d580 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2d590 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2d5a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2d5b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2d5c0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
2d5d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2d5e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
2d5f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
2d600 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
2d610 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2d620 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
2d630 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
2d640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
2d650 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
2d660 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
2d670 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 Name.**.** ^Ret
2d680 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 urn the index of
2d690 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
2d6a0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 r given its name
2d6b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 . ^The.** index
2d6c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
2d6d0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 is suitable for
2d6e0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e use as the secon
2d6f0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
2d700 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
2d710 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2d720 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a d()]. ^A zero.*
2d730 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 * is returned if
2d740 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 no matching par
2d750 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e ameter is found.
2d760 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 ^The parameter
2d770 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
2d780 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
2d790 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
2d7a0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
2d7b0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
2d7c0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
2d7d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
2d7e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
2d7f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2d800 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2d810 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
2d820 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2d830 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
2d840 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
2d850 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2d860 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2d870 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2d880 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2d890 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2d8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2d8b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
2d8c0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 e);../*.** CAPI3
2d8d0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 REF: Reset All B
2d8e0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 indings On A Pre
2d8f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
2d900 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 **.** ^Contrary
2d910 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
2d920 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
2d930 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
2d940 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
2d950 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2d960 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
2d970 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
2d980 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
2d990 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
2d9a0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f to reset all ho
2d9b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f st parameters to
2d9c0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 NULL..*/.SQLITE
2d9d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2d9e0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
2d9f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2da00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2da10 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
2da20 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
2da30 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e et.**.** ^Return
2da40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2da50 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
2da60 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 sult set returne
2da70 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 d by the.** [pre
2da80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2da90 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 . ^This routine
2daa0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 returns 0 if pSt
2dab0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 mt is an SQL.**
2dac0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 statement that d
2dad0 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 oes not return d
2dae0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ata (for example
2daf0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a an [UPDATE])..*
2db00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2db10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2db20 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f nt()].*/.SQLITE_
2db30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2db40 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c column_count(sql
2db50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2db60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2db70 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 EF: Column Names
2db80 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
2db90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
2dba0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2dbb0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 e name assigned
2dbc0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 to a particular
2dbd0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 column.** in the
2dbe0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 result set of a
2dbf0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2dc00 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ent. ^The sqlit
2dc10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
2dc20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
2dc30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
2dc40 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
2dc50 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
2dc60 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 g.** and sqlite3
2dc70 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
2dc80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2dc90 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
2dca0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 minated.** UTF-1
2dcb0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 6 string. ^The
2dcc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2dcd0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 is the [prepared
2dce0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 statement].** t
2dcf0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
2dd00 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2dd10 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f ement. ^The seco
2dd20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
2dd30 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 the.** column nu
2dd40 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 mber. ^The left
2dd50 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
2dd60 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e umber 0..**.** ^
2dd70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2dd80 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 ing pointer is v
2dd90 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 alid until eithe
2dda0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
2ddb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 statement].** is
2ddc0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 destroyed by [s
2ddd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2dde0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
2ddf0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
2de00 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
2de10 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
2de20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
2de30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
2de40 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
2de50 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
2de60 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f the next call to
2de70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
2de80 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c mn_name() or sql
2de90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2dea0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 16() on the same
2deb0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e column..**.** ^
2dec0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
2ded0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 c() fails during
2dee0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 the processing
2def0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e of either routin
2df00 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c e.** (for exampl
2df10 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 e during a conve
2df20 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 rsion from UTF-8
2df30 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e to UTF-16) then
2df40 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
2df50 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
2df60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
2df70 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 of a result colu
2df80 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 mn is the value
2df90 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 of the "AS" clau
2dfa0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 se for.** that c
2dfb0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 olumn, if there
2dfc0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e is an AS clause.
2dfd0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f If there is no
2dfe0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 AS clause.** th
2dff0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 en the name of t
2e000 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 he column is uns
2e010 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 pecified and may
2e020 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 change from.**
2e030 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 one release of S
2e040 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 QLite to the nex
2e050 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
2e060 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
2e070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2e080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e090 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
2e0a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
2e0b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2e0c0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2e0d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
2e0e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
2e0f0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
2e100 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
2e110 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2e120 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
2e130 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
2e140 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
2e150 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 able, and.** tab
2e160 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 le column that i
2e170 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 s the origin of
2e180 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 a particular res
2e190 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a ult column in.**
2e1a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2e1b0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ent..** ^The nam
2e1c0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2e1d0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
2e1e0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
2e1f0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
2e200 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
2e210 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2e220 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
2e230 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
2e240 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
2e250 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
2e260 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2e270 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
2e280 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
2e290 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2e2a0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
2e2b0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
2e2c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
2e2d0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
2e2e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2e2f0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
2e300 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
2e310 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2e320 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
2e330 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
2e340 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
2e350 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
2e360 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2e370 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
2e380 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
2e390 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 * or until the s
2e3a0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
2e3b0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 is requested.**
2e3c0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 again in a diffe
2e3d0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a rent encoding..*
2e3e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 *.** ^The names
2e3f0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
2e400 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
2e410 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
2e420 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
2e430 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
2e440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2e450 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2e460 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
2e470 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
2e480 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 tatement]..** ^T
2e490 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
2e4a0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2e4b0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
2e4c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 result column re
2e4d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
2e4e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
2e4f0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
2e500 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
2e510 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 ent..** ^The lef
2e520 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 t-most column is
2e530 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 column 0 for th
2e540 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
2e550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 .** ^If the Nth
2e560 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
2e570 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
2e580 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
2e590 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
2e5a0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
2e5b0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
2e5c0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
2e5d0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
2e5e0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 * NULL. ^These
2e5f0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
2e600 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
2e610 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
2e620 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
2e630 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 ccurs. ^Otherwi
2e640 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
2e650 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2e660 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2e670 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 e, table,.** or
2e680 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
2e690 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
2e6a0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
2e6b0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 om..**.** ^As wi
2e6c0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
2e6d0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
2e6e0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 whose names end
2e6f0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e with "16" return
2e700 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 .** UTF-16 encod
2e710 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 ed strings and t
2e720 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
2e730 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
2e740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 .**.** ^These AP
2e750 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
2e760 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2e770 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2e780 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2e790 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2e7a0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2e7b0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2e7c0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 bol..**.** If tw
2e7d0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2e7e0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
2e7f0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
2e800 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
2e810 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
2e820 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
2e830 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
2e840 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
2e850 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
2e860 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2e870 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2e880 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2e890 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c or more.** [sql
2e8a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2e8b0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
2e8c0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
2e8d0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 rfaces].** for t
2e8e0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
2e8f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
2e900 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
2e910 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 * at the same ti
2e920 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
2e930 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2e940 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2e950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
2e960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2e970 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
2e980 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2e990 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2e9a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2e9b0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
2e9c0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2e9d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2e9e0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
2e9f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
2ea00 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ble_name(sqlite3
2ea10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2ea20 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2ea30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2ea40 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
2ea50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2ea60 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2ea70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
2ea80 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
2ea90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2eaa0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2eab0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2eac0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2ead0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2eae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2eaf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2eb00 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2eb10 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2eb20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2eb30 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2eb40 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2eb50 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2eb60 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2eb70 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2eb80 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2eb90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2eba0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2ebb0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2ebc0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2ebd0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2ebe0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2ebf0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2ec00 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2ec10 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2ec20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2ec30 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2ec40 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2ec50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2ec60 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2ec70 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2ec80 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2ec90 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2eca0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2ecb0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2ecc0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2ecd0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2ece0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2ecf0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2ed00 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2ed10 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2ed20 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2ed30 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2ed40 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2ed50 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2ed60 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2ed70 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2ed80 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2ed90 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2eda0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2edb0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2edc0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2edd0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2ede0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2edf0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2ee00 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2ee10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2ee20 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2ee30 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2ee40 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2ee50 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2ee60 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2ee70 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2ee80 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2ee90 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2eea0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2eeb0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2eec0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2eed0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2eee0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2eef0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2ef00 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2ef10 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2ef20 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2ef30 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2ef40 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2ef50 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2ef60 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2ef70 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2ef80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
2ef90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2efa0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
2efb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2efc0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2efd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2efe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
2eff0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
2f000 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
2f010 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 CAPI3REF: Evalu
2f020 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
2f030 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ment.**.** After
2f040 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2f050 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
2f060 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
2f070 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
2f080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2f090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2f0a0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2f0b0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 one of the legac
2f0c0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 y.** interfaces
2f0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2f0e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2f0f0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 prepare16()], th
2f100 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d is function.** m
2f110 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e ust be called on
2f120 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
2f130 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 to evaluate the
2f140 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
2f150 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
2f160 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
2f170 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
2f180 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 () interface dep
2f190 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 end.** on whethe
2f1a0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 r the statement
2f1b0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 was prepared usi
2f1c0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 ng the newer "v2
2f1d0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b " interface.** [
2f1e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2f1f0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
2f200 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2f210 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 )] or the older
2f220 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 legacy.** interf
2f230 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ace [sqlite3_pre
2f240 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2f250 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2f260 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ]. The use of t
2f270 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 he.** new "v2" i
2f280 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
2f290 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 mmended for new
2f2a0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 applications but
2f2b0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2f2c0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f nterface will co
2f2d0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 ntinue to be sup
2f2e0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ported..**.** ^I
2f2f0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 n the legacy int
2f300 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
2f310 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
2f320 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
2f330 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 BUSY],.** [SQLIT
2f340 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 E_DONE], [SQLITE
2f350 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 _ROW], [SQLITE_E
2f360 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 RROR], or [SQLIT
2f370 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 E_MISUSE]..** ^W
2f380 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
2f390 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 erface, any of t
2f3a0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 he other [result
2f3b0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 codes] or.** [e
2f3c0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
2f3d0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 odes] might be r
2f3e0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e eturned as well.
2f3f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2f400 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
2f410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2f420 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
2f430 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
2f440 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
2f450 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
2f460 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 its job. ^If th
2f470 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2f480 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
2f490 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
2f4a0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
2f4b0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
2f4c0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
2f4d0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
2f4e0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
2f4f0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
2f500 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
2f510 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c ithin an.** expl
2f520 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
2f530 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 then you should
2f540 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 rollback the tr
2f550 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 ansaction before
2f560 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a .** continuing..
2f570 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 **.** ^[SQLITE_D
2f580 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ONE] means that
2f590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
2f5a0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
2f5b0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 ting.** successf
2f5c0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 ully. sqlite3_s
2f5d0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 tep() should not
2f5e0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e be called again
2f5f0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c on this virtual
2f600 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 .** machine with
2f610 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e out first callin
2f620 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2f630 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2f640 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2f650 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 ine back to its
2f660 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a initial state..*
2f670 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c *.** ^If the SQL
2f680 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 statement being
2f690 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e executed return
2f6a0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e s any data, then
2f6b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a [SQLITE_ROW].**
2f6c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 is returned eac
2f6d0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 h time a new row
2f6e0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 of data is read
2f6f0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 y for processing
2f700 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 by the.** calle
2f710 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 r. The values ma
2f720 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 y be accessed us
2f730 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 ing the [column
2f740 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
2f750 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 ]..** sqlite3_st
2f760 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 ep() is called a
2f770 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 gain to retrieve
2f780 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 the next row of
2f790 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 data..**.** ^[S
2f7a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 QLITE_ERROR] mea
2f7b0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 ns that a run-ti
2f7c0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 me error (such a
2f7d0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a s a constraint.*
2f7e0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 * violation) has
2f7f0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 occurred. sqli
2f800 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c te3_step() shoul
2f810 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 d not be called
2f820 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 again on.** the
2f830 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 VM. More informa
2f840 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e tion may be foun
2f850 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
2f860 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
2f870 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 .** ^With the le
2f880 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2f890 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 a more specific
2f8a0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 error code (for
2f8b0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c example,.** [SQL
2f8c0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 ITE_INTERRUPT],
2f8d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c [SQLITE_SCHEMA],
2f8e0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 [SQLITE_CORRUPT
2f8f0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 ], and so forth)
2f900 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 .** can be obtai
2f910 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b ned by calling [
2f920 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2f930 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 on the.** [prep
2f940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2f950 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 ^In the "v2" i
2f960 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
2f970 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
2f980 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
2f990 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
2f9a0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2f9b0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
2f9c0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
2f9d0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
2f9e0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
2f9f0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
2fa00 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
2fa10 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
2fa20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fa30 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
2fa40 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
2fa50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
2fa60 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
2fa70 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a one that had.**
2fa80 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
2fa90 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 rned [SQLITE_ERR
2faa0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OR] or [SQLITE_D
2fab0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 ONE]. Or it cou
2fac0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 ld.** be the cas
2fad0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 e that the same
2fae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2faf0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 ion is being use
2fb00 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d d by two or.** m
2fb10 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 ore threads at t
2fb20 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 he same moment i
2fb30 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f n time..**.** Fo
2fb40 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f r all versions o
2fb50 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 f SQLite up to a
2fb60 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 nd including 3.6
2fb70 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f .23.1, a call to
2fb80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2fb90 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 et()] was requir
2fba0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
2fbb0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 _step() returned
2fbc0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 anything.** oth
2fbd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2fbe0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 ROW] before any
2fbf0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
2fc00 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 ation of.** sqli
2fc10 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 te3_step(). Fai
2fc20 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 lure to reset th
2fc30 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2fc40 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b ment using .** [
2fc50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2fc60 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e would result in
2fc70 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 an [SQLITE_MISU
2fc80 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a SE] return from.
2fc90 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
2fca0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 ). But after ve
2fcb0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 rsion 3.6.23.1,
2fcc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
2fcd0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 egan.** calling
2fce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2fcf0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 ] automatically
2fd00 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
2fd10 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 ance rather.** t
2fd20 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
2fd30 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2fd40 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 This is not cons
2fd50 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 idered a compati
2fd60 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 bility.** break
2fd70 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c because any appl
2fd80 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 ication that eve
2fd90 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 r receives an SQ
2fda0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f LITE_MISUSE erro
2fdb0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 r.** is broken b
2fdc0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 y definition. T
2fdd0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
2fde0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 AUTORESET] compi
2fdf0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a le-time option.*
2fe00 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
2fe10 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 restore the leg
2fe20 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a acy behavior..**
2fe30 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
2fe40 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
2fe50 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
2fe60 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
2fe70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
2fe80 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
2fe90 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
2fea0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
2feb0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
2fec0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
2fed0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
2fee0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
2fef0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
2ff00 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
2ff10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2ff20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
2ff30 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
2ff40 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
2ff50 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
2ff60 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
2ff70 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
2ff80 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
2ff90 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
2ffa0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
2ffb0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
2ffc0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
2ffd0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
2ffe0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
2fff0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
30000 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
30010 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
30020 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
30030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
30040 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
30050 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
30060 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
30070 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
30080 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
30090 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
300a0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
300b0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
300c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
300d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
300e0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
300f0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
30100 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
30110 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
30120 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
30130 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ended..*/.SQLITE
30140 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
30150 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 _step(sqlite3_st
30160 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
30170 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 I3REF: Number of
30180 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 columns in a re
30190 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e sult set.**.** ^
301a0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
301b0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 _count(P) interf
301c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
301d0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
301e0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 s in the.** curr
301f0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
30200 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 esult set of [pr
30210 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30220 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 ] P..** ^If prep
30230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 ared statement P
30240 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 does not have r
30250 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 esults ready to
30260 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 return.** (via c
30270 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c alls to the [sql
30280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 ite3_column_int
30290 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e | sqlite3_column
302a0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 _*()] of.** inte
302b0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c rfaces) then sql
302c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
302d0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a P) returns 0..**
302e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
302f0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 ta_count(P) rout
30300 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 ine also returns
30310 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 0 if P is a NUL
30320 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 L pointer..** ^T
30330 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
30340 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
30350 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 returns 0 if th
30360 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
30370 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
30380 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 tep](P) returned
30390 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
303a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
303b0 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 ta_count(P).** w
303c0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a ill return non-z
303d0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 ero if previous
303e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
303f0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
30400 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f ed.** [SQLITE_RO
30410 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 W], except in th
30420 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 e case of the [P
30430 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 RAGMA incrementa
30440 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 l_vacuum].** whe
30450 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 re it always ret
30460 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 urns zero since
30470 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 each step of tha
30480 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 t multi-step.**
30490 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 pragma returns 0
304a0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 columns of data
304b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
304c0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d : [sqlite3_colum
304d0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 n_count()].*/.SQ
304e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
304f0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
30500 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
30510 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
30520 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 I3REF: Fundament
30530 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 al Datatypes.**
30540 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
30550 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 _TEXT.**.** ^(Ev
30560 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c ery value in SQL
30570 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 ite has one of f
30580 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 ive fundamental
30590 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a datatypes:.**.**
305a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 <ul>.** <li> 64
305b0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
305c0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ger.** <li> 64-b
305d0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 it IEEE floating
305e0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a point number.**
305f0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 <li> string.**
30600 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 <li> BLOB.** <li
30610 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 > NULL.** </ul>)
30620 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f ^.**.** These co
30630 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
30640 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
30650 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
30660 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
30670 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
30680 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
30690 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
306a0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
306b0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
306c0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
306d0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
306e0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
306f0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
30700 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
30710 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
30720 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c se SQLITE3_TEXT,
30730 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 not.** SQLITE_T
30740 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 EXT..*/.#define
30750 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 SQLITE_INTEGER
30760 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
30770 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 _FLOAT 2.#def
30780 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 ine SQLITE_BLOB
30790 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
307a0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a LITE_NULL 5.
307b0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 #ifdef SQLITE_TE
307c0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 XT.# undef SQLIT
307d0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 E_TEXT.#else.# d
307e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 efine SQLITE_TEX
307f0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 T 3.#endif.#
30800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 define SQLITE3_T
30810 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a EXT 3../*.**
30820 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
30830 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 t Values From A
30840 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 Query.** KEYWORD
30850 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 S: {column acces
30860 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a s functions}.**.
30870 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
30880 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 s form the "resu
30890 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 lt set" interfac
308a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e..**.** ^These
308b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
308c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
308d0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
308e0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
308f0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
30900 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
30910 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
30920 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
30930 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
30940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
30950 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
30960 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
30970 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
30980 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
30990 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
309a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
309b0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
309c0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
309d0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
309e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
309f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
30a00 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
30a10 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
30a20 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
30a30 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
30a40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
30a50 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
30a60 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
30a70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
30a80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
30a90 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
30aa0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
30ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
30ac0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
30ad0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
30ae0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
30af0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
30b00 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
30b10 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
30b20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
30b30 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
30b40 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
30b50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
30b60 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
30b70 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
30b80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
30b90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
30ba0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
30bb0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
30bc0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
30bd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30be0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
30bf0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
30c00 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
30c10 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
30c20 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
30c30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
30c40 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
30c50 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
30c60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
30c70 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
30c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
30c90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
30ca0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
30cb0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
30cc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
30cd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
30ce0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
30cf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
30d00 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
30d10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
30d20 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
30d30 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
30d40 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
30d50 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
30d60 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
30d70 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
30d80 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
30d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
30da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
30db0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
30dc0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
30dd0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
30de0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ype code] for th
30df0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 e initial data t
30e00 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 ype.** of the re
30e10 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 sult column. ^T
30e20 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
30e30 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
30e40 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
30e50 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
30e60 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
30e70 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
30e80 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
30e90 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
30ea0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
30eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
30ec0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
30ed0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
30ee0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
30ef0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
30f00 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
30f10 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
30f20 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
30f30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
30f40 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
30f50 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
30f60 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
30f70 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
30f80 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
30f90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
30fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
30fb0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
30fc0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
30fd0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 sion..**.** ^If
30fe0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
30ff0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
31000 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
31010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31020 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
31030 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
31040 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
31050 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
31060 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
31070 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
31080 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
31090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
310a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
310b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
310c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
310d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
310e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
310f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
31100 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
31110 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
31120 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 lumn_bytes() use
31130 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
31140 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
31150 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
31160 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e to a UTF-8 strin
31170 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
31180 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
31190 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
311a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
311b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
311c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
311d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 umn_bytes() retu
311e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
311f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
31200 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
31210 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 16 string then t
31220 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
31230 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 n_bytes16().** r
31240 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
31250 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
31260 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
31270 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
31280 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
31290 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 a UTF-8 string,
312a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
312b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f umn_bytes16() co
312c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
312d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 ring to UTF-16 a
312e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
312f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
31300 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
31310 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
31320 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
31330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31340 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 tes16() uses.**
31350 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
31360 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
31370 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
31380 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e UTF-16 string an
31390 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
313a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
313b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
313c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
313d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
313e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
313f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e bytes16() return
31400 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s zero..**.** ^T
31410 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
31420 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
31430 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
31440 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
31450 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
31460 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] do not include
31470 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
31480 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 ators at the end
31490 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
314a0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 g. ^For clarity
314b0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 : the values ret
314c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
314d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
314e0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
314f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
31500 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 ()] are the numb
31510 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
31520 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
31530 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
31540 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
31550 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 * ^Strings retur
31560 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
31570 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
31580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31590 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
315a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
315b0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
315c0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
315d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
315e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
315f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
31600 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
31610 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 BLOB is a NULL p
31620 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
31630 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e he object return
31640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
31650 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
31660 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 s an.** [unprote
31670 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
31680 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 ue] object. An
31690 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
316a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
316b0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
316c0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 used with [sqlit
316d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
316e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
316f0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a sult_value()]..*
31700 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 * If the [unprot
31710 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
31720 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 lue] object retu
31730 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
31740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
31750 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 ()] is used in a
31760 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e ny other way, in
31770 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a cluding calls.**
31780 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b to routines lik
31790 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
317a0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 _int()], [sqlite
317b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
317c0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
317d0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
317e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
317f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
31800 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
31810 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 ines attempt to
31820 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 convert the valu
31830 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 e where appropri
31840 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 ate. ^For.** ex
31850 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e ample, if the in
31860 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
31870 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 ation is FLOAT a
31880 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 nd a text result
31890 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 .** is requested
318a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 , [sqlite3_snpri
318b0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 ntf()] is used i
318c0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 nternally to per
318d0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 form the.** conv
318e0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 ersion automatic
318f0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c ally. ^(The fol
31900 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
31910 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
31920 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ions.** that are
31930 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
31940 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
31950 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
31960 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 ">.** <tr><th> I
31970 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 nternal<br>Type
31980 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 <th> Requested<b
31990 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e r>Type <th> Con
319a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 version.**.** <t
319b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
319c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
319d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a td> Result is 0.
319e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
319f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 L <td> FLOAT
31a00 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
31a10 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 is 0.0.** <tr><t
31a20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
31a30 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
31a40 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 Result is NULL p
31a50 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
31a60 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
31a70 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
31a80 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 Result is NULL p
31a90 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
31aa0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
31ab0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
31ac0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 Convert from int
31ad0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a eger to float.**
31ae0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
31af0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 R <td> TEXT
31b00 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
31b10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e dering of the in
31b20 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
31b30 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
31b40 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
31b50 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e ame as INTEGER->
31b60 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
31b70 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
31b80 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
31b90 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 nvert from float
31ba0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c to integer.** <
31bb0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
31bc0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
31bd0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
31be0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 ring of the floa
31bf0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 t.** <tr><td> F
31c00 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c LOAT <td> BL
31c10 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
31c20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a as FLOAT->TEXT.*
31c30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
31c40 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
31c50 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 <td> Use atoi
31c60 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
31c70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c TEXT <td> FL
31c80 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 OAT <td> Use
31c90 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
31ca0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
31cb0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
31cc0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
31cd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
31ce0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
31cf0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
31d00 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 XT then use atoi
31d10 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
31d20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
31d30 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
31d40 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e ert to TEXT then
31d50 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c use atof().** <
31d60 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
31d70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
31d80 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 <td> Add a zero
31d90 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 terminator if ne
31da0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e eded.** </table>
31db0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
31dc0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 >)^.**.** The ta
31dd0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 ble above makes
31de0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 reference to sta
31df0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 ndard C library
31e00 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 functions atoi()
31e10 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 .** and atof().
31e20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 SQLite does not
31e30 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 really use thes
31e40 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 e functions. It
31e50 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 has its.** own
31e60 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 equivalent inter
31e70 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 nal routines. T
31e80 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 he atoi() and at
31e90 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a of() names are.*
31ea0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 * used in the ta
31eb0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 ble for brevity
31ec0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 and because they
31ed0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f are familiar to
31ee0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 most.** C progr
31ef0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f ammers..**.** No
31f00 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 te that when typ
31f10 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 e conversions oc
31f20 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 cur, pointers re
31f30 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a turned by prior.
31f40 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ** calls to sqli
31f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
31f60 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ), sqlite3_colum
31f70 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 n_text(), and/or
31f80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
31f90 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 mn_text16() may
31fa0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a be invalidated..
31fb0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 ** Type conversi
31fc0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 ons and pointer
31fd0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 invalidations mi
31fe0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ght occur.** in
31ff0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
32000 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ses:.**.** <ul>.
32010 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
32020 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 ial content is a
32030 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 BLOB and sqlite
32040 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
32050 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
32060 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
32070 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 () is called. A
32080 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
32090 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e might.** n
320a0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 eed to be added
320b0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f to the string.</
320c0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
320d0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
320e0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e is UTF-8 text an
320f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
32100 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a _bytes16() or.**
32110 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
32120 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 lumn_text16() is
32130 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
32140 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
32150 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
32160 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a to UTF-16.</li>.
32170 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
32180 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
32190 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 TF-16 text and s
321a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
321b0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 tes() or.**
321c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
321d0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 text() is called
321e0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
321f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
32200 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
32210 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 8.</li>.** </ul>
32220 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 .**.** ^Conversi
32230 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d ons between UTF-
32240 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 16be and UTF-16l
32250 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e e are always don
32260 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 e in place and d
32270 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 o.** not invalid
32280 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e ate a prior poin
32290 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 ter, though of c
322a0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e ourse the conten
322b0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a t of the buffer.
322c0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f ** that the prio
322d0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 r pointer refere
322e0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 nces will have b
322f0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f een modified. O
32300 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 ther kinds.** of
32310 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 conversion are
32320 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 done in place wh
32330 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c en it is possibl
32340 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 e, but sometimes
32350 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 they.** are not
32360 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e possible and in
32370 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 those cases pri
32380 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 or pointers are
32390 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a invalidated..**.
323a0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e ** The safest an
323b0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d d easiest to rem
323c0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 ember policy is
323d0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
323e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
323f0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
32400 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
32410 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c <ul>.** <li>sql
32420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
32430 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
32440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
32450 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
32460 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
32470 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 n_blob() followe
32480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
32490 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
324a0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
324b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
324c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
324d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
324e0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f s16()</li>.** </
324f0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 ul>.**.** In oth
32500 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 er words, you sh
32510 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 ould call sqlite
32520 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
32530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
32540 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 mn_blob(), or sq
32550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32560 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 t16() first to f
32570 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a orce the result.
32580 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 ** into the desi
32590 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e red format, then
325a0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
325b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
325c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
325d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f umn_bytes16() to
325e0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f find the size o
325f0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 f the result. D
32600 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a o not mix calls.
32610 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ** to sqlite3_co
32620 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 lumn_text() or s
32630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
32640 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 ob() with calls
32650 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
32660 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 lumn_bytes16(),
32670 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 and do not mix c
32680 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
32690 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a column_text16().
326a0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f ** with calls to
326b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
326c0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e bytes()..**.** ^
326d0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 The pointers ret
326e0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 urned are valid
326f0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e until a type con
32700 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 version occurs a
32710 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 s.** described a
32720 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b bove, or until [
32730 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
32740 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
32750 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
32760 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
32770 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 is called. ^The
32780 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 memory space us
32790 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e ed to hold strin
327a0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 gs.** and BLOBs
327b0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 is freed automat
327c0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e ically. Do <b>n
327d0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 ot</b> pass the
327e0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
327f0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
32800 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 lumn_blob()], [s
32810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32820 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f xt()], etc. into
32830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
32840 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 e()]..**.** ^(If
32850 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
32860 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
32870 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
32880 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
32890 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
328a0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
328b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
328c0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
328d0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
328e0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
328f0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
32900 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
32910 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
32920 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
32930 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
32940 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
32950 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
32960 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a QLITE_NOMEM].)^.
32970 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
32980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
32990 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 3_column_blob(sq
329a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
329b0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
329c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
329d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 olumn_bytes(sqli
329e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
329f0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
32a00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
32a10 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
32a20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
32a30 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
32a40 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
32a50 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 column_double(sq
32a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
32a70 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
32a80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
32a90 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
32aa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
32ab0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 l);.SQLITE_API s
32ac0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
32ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
32ae0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
32af0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
32b00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 TE_API const uns
32b10 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
32b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
32b30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
32b40 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
32b50 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
32b60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
32b70 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
32b80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
32b90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
32ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32bb0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
32bc0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
32bd0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
32be0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f _value *sqlite3_
32bf0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
32c00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
32c10 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
32c20 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
32c30 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
32c40 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
32c50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
32c60 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 inalize() functi
32c70 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 on is called to
32c80 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 delete a [prepar
32c90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
32ca0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
32cb0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ecent evaluation
32cc0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e of the statemen
32cd0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f t encountered no
32ce0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 errors.** or if
32cf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
32d00 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 s never been eva
32d10 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c luated, then sql
32d20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
32d30 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 returns.** SQLIT
32d40 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d E_OK. ^If the m
32d50 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
32d60 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 ation of stateme
32d70 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 nt S failed, the
32d80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e n.** sqlite3_fin
32d90 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 alize(S) returns
32da0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 the appropriate
32db0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
32dc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 .** [extended er
32dd0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a ror code]..**.**
32de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 ^The sqlite3_fi
32df0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e nalize(S) routin
32e00 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 e can be called
32e10 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 at any point dur
32e20 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 ing.** the life
32e30 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 cycle of [prepar
32e40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a ed statement] S:
32e50 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 .** before state
32e60 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 ment S is ever e
32e70 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a valuated, after.
32e80 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 ** one or more c
32e90 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
32ea0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 _reset()], or af
32eb0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 ter any call.**
32ec0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
32ed0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f ()] regardless o
32ee0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
32ef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 the statement h
32f00 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 as.** completed
32f10 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a execution..**.**
32f20 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 ^Invoking sqlit
32f30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e e3_finalize() on
32f40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
32f50 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
32f60 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 -op..**.** The a
32f70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
32f80 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b finalize every [
32f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32fa0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 nt] in order to
32fb0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 avoid.** resourc
32fc0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 e leaks. It is
32fd0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 a grievous error
32fe0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 for the applica
32ff0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 tion to try to u
33000 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 se.** a prepared
33010 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
33020 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e it has been fin
33030 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 alized. Any use
33040 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a of a prepared.*
33050 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 * statement afte
33060 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
33070 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 nalized can resu
33080 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
33090 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 and.** undesirab
330a0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 le behavior such
330b0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e as segfaults an
330c0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f d heap corruptio
330d0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
330e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e int sqlite3_fin
330f0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
33100 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
33110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
33120 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
33130 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
33140 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
33150 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f _reset() functio
33160 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 n is called to r
33170 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 eset a [prepared
33180 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
33190 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 bject back to it
331a0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c s initial state,
331b0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d ready to be re-
331c0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e executed..** ^An
331d0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
331e0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
331f0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
33200 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
33210 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
33220 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
33230 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
33240 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
33250 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
33260 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
33270 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
33280 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
33290 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
332a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
332b0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 rface resets the
332c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
332d0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 ment] S.** back
332e0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
332f0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e of its program.
33300 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d .**.** ^If the m
33310 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
33320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
33330 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 (S)] for the.**
33340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
33350 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 ent] S returned
33360 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
33370 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a [SQLITE_DONE],.*
33380 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 * or if [sqlite3
33390 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 _step(S)] has ne
333a0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 ver before been
333b0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 called on S,.**
333c0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 then [sqlite3_re
333d0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 set(S)] returns
333e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
333f0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
33400 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
33410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
33420 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
33430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
33440 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
33450 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b error, then.** [
33460 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
33470 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 ] returns an app
33480 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
33490 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
334a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
334b0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 (S)] interface d
334c0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
334d0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 he values.** of
334e0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e any [sqlite3_bin
334f0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d d_blob|bindings]
33500 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 on the [prepare
33510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
33520 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
33530 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 t sqlite3_reset(
33540 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
33550 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
33560 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 I3REF: Create Or
33570 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 Redefine SQL Fu
33580 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f nctions.** KEYWO
33590 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 RDS: {function c
335a0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
335b0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
335c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
335d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
335e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
335f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33600 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
33610 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 s}.**.** ^These
33620 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
33630 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
33640 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
33650 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
33660 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
33670 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
33680 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
33690 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
336a0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
336b0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
336c0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
336d0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
336e0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
336f0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
33700 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
33710 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
33720 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
33730 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
33740 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
33750 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
33760 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
33770 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
33780 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
33790 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
337a0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
337b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
337c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
337d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
337e0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
337f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
33800 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
33810 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
33820 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
33830 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
33840 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
33850 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
33860 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
33870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33880 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
33890 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
338a0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
338b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
338c0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
338d0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
338e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
338f0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
33900 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
33910 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
33920 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
33930 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
33940 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
33950 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
33960 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
33970 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
33980 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
33990 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
339a0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
339b0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
339c0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
339d0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
339e0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
339f0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
33a00 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
33a10 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
33a20 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
33a30 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
33a40 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
33a50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
33a60 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
33a70 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
33a80 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
33a90 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
33aa0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
33ab0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
33ac0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
33ad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
33ae0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
33af0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
33b00 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
33b10 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
33b20 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
33b30 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
33b40 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
33b50 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
33b60 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
33b70 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
33b80 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
33b90 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
33ba0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
33bb0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
33bc0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
33bd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
33be0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
33bf0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
33c00 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
33c10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
33c20 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
33c30 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
33c40 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
33c50 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
33c60 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 s. Every SQL fu
33c70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
33c80 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 ation must be ab
33c90 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 le to work.** wi
33ca0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 th UTF-8, UTF-16
33cb0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e le, or UTF-16be.
33cc0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 But some imple
33cd0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 mentations may b
33ce0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 e.** more effici
33cf0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 ent with one enc
33d00 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 oding than anoth
33d10 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 er. ^An applica
33d20 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f tion may.** invo
33d30 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
33d40 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 e_function() or
33d50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
33d60 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 unction16() mult
33d70 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 iple.** times wi
33d80 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 th the same func
33d90 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 tion but with di
33da0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f fferent values o
33db0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e f eTextRep..** ^
33dc0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
33dd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
33de0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
33df0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
33e00 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
33e10 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
33e20 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
33e30 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
33e40 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
33e50 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
33e60 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
33e70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
33e80 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
33e90 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e what text.** en
33ea0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
33eb0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
33ec0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
33ed0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e be [SQLITE_ANY].
33ee0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 .**.** ^(The fif
33ef0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
33f00 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 an arbitrary poi
33f10 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 nter. The imple
33f20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
33f30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e .** function can
33f40 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 gain access to
33f50 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 this pointer usi
33f60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ng [sqlite3_user
33f70 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a _data()].)^.**.*
33f80 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 * ^The sixth, se
33f90 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 venth and eighth
33fa0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
33fb0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
33fc0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
33fd0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
33fe0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
33ff0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
34000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
34010 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e .** aggregate. ^
34020 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e A scalar SQL fun
34030 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
34040 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
34050 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a of the xFunc.**
34060 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 callback only;
34070 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 NULL pointers mu
34080 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 st be passed as
34090 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 the xStep and xF
340a0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 inal.** paramete
340b0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 rs. ^An aggregat
340c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
340d0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
340e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 mentation of xSt
340f0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c ep.** and xFinal
34100 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 and NULL pointe
34110 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 r must be passed
34120 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 for xFunc. ^To
34130 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 delete an existi
34140 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 ng.** SQL functi
34150 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c on or aggregate,
34160 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 pass NULL point
34170 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ers for all thre
34180 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 e function.** ca
34190 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e llbacks..**.** ^
341a0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 (If the ninth pa
341b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
341c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
341d0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e on_v2() is not N
341e0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 ULL,.** then it
341f0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f is destructor fo
34200 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
34210 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 n data pointer.
34220 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 .** The destruct
34230 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 or is invoked wh
34240 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
34250 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 is deleted, eith
34260 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f er by being.** o
34270 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 verloaded or whe
34280 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
34290 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
342a0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 .)^.** ^The dest
342b0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 ructor is also i
342c0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 nvoked if the ca
342d0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
342e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
342f0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 _v2() fails..**
34300 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 ^When the destru
34310 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 ctor callback of
34320 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d the tenth param
34330 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c eter is invoked,
34340 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 it.** is passed
34350 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
34360 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f nt which is a co
34370 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 py of the applic
34380 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 ation data .** p
34390 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 ointer which was
343a0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d the fifth param
343b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
343c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
343d0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 v2()..**.** ^It
343e0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
343f0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c register multipl
34400 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
34410 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a s of the same.**
34420 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 functions with
34430 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
34440 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 t with either di
34450 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 ffering numbers
34460 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 of.** arguments
34470 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 or differing pre
34480 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
34490 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 dings. ^SQLite
344a0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 will use.** the
344b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 implementation t
344c0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 hat most closely
344d0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 matches the way
344e0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a in which the.**
344f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
34500 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 used. ^A funct
34510 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
34520 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 on with a non-ne
34530 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 gative.** nArg p
34540 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 arameter is a be
34550 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 tter match than
34560 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 a function imple
34570 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a mentation with.*
34580 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 * a negative nAr
34590 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 g. ^A function
345a0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 where the prefer
345b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
345c0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 g.** matches the
345d0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 database encodi
345e0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a ng is a better.*
345f0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 * match than a f
34600 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
34610 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 e encoding is di
34620 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 fferent. .** ^A
34630 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
34640 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
34650 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 ference is betwe
34660 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 en UTF16le and U
34670 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 TF16be.** is a c
34680 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e loser match than
34690 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
346a0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
346b0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 ifference is.**
346c0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 between UTF8 and
346d0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 UTF16..**.** ^B
346e0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
346f0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 s may be overloa
34700 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 ded by new appli
34710 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
34720 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 unctions..**.**
34730 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ^An application-
34740 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34750 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
34760 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 call other.** S
34770 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
34780 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 . However, such
34790 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a calls must not.
347a0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ** close the dat
347b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
347c0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 nor finalize or
347d0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
347e0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
347f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 in which the fu
34800 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
34810 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
34820 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
34830 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
34840 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
34850 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
34860 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
34870 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
34880 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
34890 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
348a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
348b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
348c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
348d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
348e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
348f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
34900 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
34910 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
34920 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 xt*).);.SQLITE_A
34930 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
34940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
34950 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
34960 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
34970 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
34980 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
34990 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
349a0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
349b0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
349c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
349d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
349e0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
349f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34a00 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
34a10 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
34a20 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
34a30 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 ontext*).);.SQLI
34a40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
34a50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
34a60 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
34a70 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
34a80 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
34a90 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
34aa0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
34ab0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
34ac0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
34ad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
34ae0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
34af0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
34b00 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
34b10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
34b20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
34b30 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
34b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 te3_context*),.
34b50 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
34b60 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a (void*).);../*.*
34b70 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 * CAPI3REF: Text
34b80 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a Encodings.**.**
34b90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 These constant
34ba0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 define integer c
34bb0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 odes that repres
34bc0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a ent the various.
34bd0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ** text encoding
34be0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 s supported by S
34bf0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
34c00 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 e SQLITE_UTF8
34c10 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
34c20 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 e SQLITE_UTF16LE
34c30 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
34c40 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 e SQLITE_UTF16BE
34c50 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
34c60 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 e SQLITE_UTF16
34c70 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 4 /*
34c80 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 Use native byte
34c90 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 order */.#define
34ca0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 SQLITE_ANY
34cb0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 5 /* s
34cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
34cd0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 nction only */.#
34ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
34cf0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 F16_ALIGNED 8
34d00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 /* sqlite3_cre
34d10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e ate_collation on
34d20 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ly */../*.** CAP
34d30 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 I3REF: Deprecate
34d40 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 d Functions.** D
34d50 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 EPRECATED.**.**
34d60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
34d70 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d are [deprecated]
34d80 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d . In order to m
34d90 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 aintain.** backw
34da0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
34db0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f ty with older co
34dc0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 de, these functi
34dd0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a ons continue .**
34de0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
34df0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 . However, new
34e00 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f applications sho
34e10 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 uld avoid.** the
34e20 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 use of these fu
34e30 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c nctions. To hel
34e40 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 p encourage peop
34e50 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 le to avoid.** u
34e60 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 sing these funct
34e70 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 ions, we are not
34e80 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 going to tell y
34e90 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e ou what they do.
34ea0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
34eb0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 TE_OMIT_DEPRECAT
34ec0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 ED.SQLITE_API SQ
34ed0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
34ee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 int sqlite3_aggr
34ef0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 egate_count(sqli
34f00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
34f10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
34f20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
34f30 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 sqlite3_expired(
34f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
34f50 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
34f60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
34f70 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 sqlite3_transfe
34f80 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
34f90 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 e3_stmt*, sqlite
34fa0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
34fb0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
34fc0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
34fd0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
34fe0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f r(void);.SQLITE_
34ff0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
35000 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 CATED void sqlit
35010 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 e3_thread_cleanu
35020 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f p(void);.SQLITE_
35030 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
35040 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
35050 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
35060 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
35070 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
35080 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
35090 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
350a0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
350b0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
350c0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
350d0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 QL Function Para
350e0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a meter Values.**.
350f0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
35100 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
35110 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
35120 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
35130 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
35140 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
35150 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
35160 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
35170 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
35180 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
35190 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 regate..**.** Th
351a0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
351b0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
351c0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
351d0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
351e0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
351f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35200 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
35210 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35220 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
35230 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
35240 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
35250 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
35260 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
35270 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
35280 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
35290 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
352a0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
352b0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
352c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
352d0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
352e0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
352f0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
35300 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
35310 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
35320 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
35330 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
35340 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
35350 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
35360 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
35370 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
35380 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
35390 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
353a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
353b0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
353c0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
353d0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
353e0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
353f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
35400 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
35410 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
35420 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
35430 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
35440 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
35450 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
35460 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
35470 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
35480 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 except that th
35490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
354a0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
354b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
354c0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
354d0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
354e0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
354f0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
35500 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
35510 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
35520 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
35530 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
35540 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
35550 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
35560 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
35570 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
35580 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
35590 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
355a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
355b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
355c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
355d0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
355e0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
355f0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
35600 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
35610 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
35620 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
35630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
35640 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
35650 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
35660 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
35670 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
35680 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
35690 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
356a0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
356b0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
356c0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
356d0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
356e0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
356f0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
35700 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
35710 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
35720 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
35730 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
35740 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
35750 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
35760 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
35770 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
35780 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
35790 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
357a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
357b0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
357c0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
357d0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
357e0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
357f0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
35800 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
35810 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
35820 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
35830 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
35840 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
35850 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
35860 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
35870 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
35880 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
35890 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
358a0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
358b0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
358c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
358d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
358e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
358f0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
35900 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
35910 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
35920 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
35930 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
35940 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
35950 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
35960 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
35970 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
35980 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
35990 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
359a0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
359b0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
359c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
359d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
359e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
359f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
35a00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
35a10 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
35a20 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
35a30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
35a40 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
35a50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
35a60 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c E_API double sql
35a70 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
35a80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
35a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
35aa0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
35ab0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
35ac0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
35ad0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
35ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
35af0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 4(sqlite3_value*
35b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
35b10 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
35b20 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
35b30 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
35b40 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
35b50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
35b60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
35b70 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
35b80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
35b90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
35ba0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
35bb0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
35bc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
35bd0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
35be0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
35bf0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
35c00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
35c10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
35c20 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
35c30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
35c40 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
35c50 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
35c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
35c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35c80 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
35c90 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
35ca0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
35cb0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
35cc0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
35cd0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
35ce0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
35cf0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
35d00 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
35d10 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
35d20 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
35d30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
35d40 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
35d50 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
35d60 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
35d70 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
35d80 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
35d90 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
35da0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
35db0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
35dc0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
35dd0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
35de0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
35df0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
35e00 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
35e10 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
35e20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
35e30 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
35e40 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
35e50 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
35e60 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
35e70 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
35e80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35e90 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
35ea0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
35eb0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
35ec0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
35ed0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
35ee0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
35ef0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
35f00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
35f10 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
35f20 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
35f30 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
35f40 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
35f50 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
35f60 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
35f70 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
35f80 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
35f90 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
35fa0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
35fb0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
35fc0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
35fd0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35fe0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
35ff0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
36000 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
36010 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
36020 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
36030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
36040 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
36050 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
36060 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
36070 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 er .** when firs
36080 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 t called if N is
36090 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
360a0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 ual to zero or i
360b0 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c f a memory.** al
360c0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 locate error occ
360d0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 urs..**.** ^(The
360e0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 amount of space
360f0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
36100 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
36110 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a context(C,N) is.
36120 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 ** determined by
36130 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
36140 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 on first succes
36150 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e sful call. Chan
36160 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ging the.** valu
36170 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 e of N in subseq
36180 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c uent call to sql
36190 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
361a0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a ontext() within.
361b0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 ** the same aggr
361c0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
361d0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 nstance will not
361e0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f resize the memo
361f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
36200 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 .)^ Within the
36210 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c xFinal callback,
36220 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 it is customary
36230 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 to set.** N=0 i
36240 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 n calls to sqlit
36250 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
36260 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 text(C,N) so tha
36270 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 t no .** pointle
36280 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ss memory alloca
36290 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a tions occur..**.
362a0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d ** ^SQLite autom
362b0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 atically frees t
362c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
362d0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 ted by .** sqlit
362e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
362f0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 text() when the
36300 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 aggregate query
36310 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a concludes..**.**
36320 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
36330 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 eter must be a c
36340 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 opy of the.** [s
36350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c qlite3_context |
36360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f SQL function co
36370 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 ntext] that is t
36380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
36390 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 er.** to the xSt
363a0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c ep or xFinal cal
363b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 lback routine th
363c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
363d0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 e aggregate.** f
363e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 unction..**.** T
363f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 his routine must
36400 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
36410 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
36420 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
36430 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
36440 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
36450 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 g..*/.SQLITE_API
36460 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 void *sqlite3_a
36470 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
36480 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36490 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
364a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
364b0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
364c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
364d0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 The sqlite3_user
364e0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 _data() interfac
364f0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
36500 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
36510 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 er that was the
36520 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 pUserData parame
36530 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 ter (the 5th par
36540 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
36550 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
36560 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
36570 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
36580 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
36590 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
365a0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
365b0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
365c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
365d0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a d function..**.*
365e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
365f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
36600 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
36610 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
36620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36630 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36640 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
36650 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
36660 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
36670 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
36680 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
36690 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
366a0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
366b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 nctions.**.** ^T
366c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 he sqlite3_conte
366d0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 xt_db_handle() i
366e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
366f0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 a copy of.** th
36700 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
36710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
36720 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 ction] (the 1st
36730 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
36740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
36750 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
36760 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
36770 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
36780 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
36790 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
367a0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
367b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
367c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
367d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
367e0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
367f0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
36800 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36810 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
36820 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
36830 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a iliary Data.**.*
36840 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
36850 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 two functions ma
36860 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 y be used by sca
36870 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e lar SQL function
36880 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
36890 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
368a0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
368b0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
368c0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
368d0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
368e0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
368f0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
36900 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
36910 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
36920 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
36930 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
36940 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
36950 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 be preserved. T
36960 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 his may.** be us
36970 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c ed, for example,
36980 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 to add a regula
36990 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 r-expression mat
369a0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 ching scalar.**
369b0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
369c0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
369d0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
369e0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 pression is stor
369f0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
36a00 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
36a10 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 h the SQL value
36a20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 passed as the re
36a30 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
36a40 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 .** pattern. Th
36a50 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
36a60 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
36a70 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
36a80 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
36a90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
36aa0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 me function so t
36ab0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c hat the original
36ac0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a pattern string.
36ad0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ** does not need
36ae0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 to be recompile
36af0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 d on each invoca
36b00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
36b10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
36b20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
36b30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
36b40 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
36b50 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
36b60 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
36b70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
36b80 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
36b90 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
36ba0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
36bb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36bc0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e function. ^If n
36bd0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 o metadata has b
36be0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e een ever.** been
36bf0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 set for the Nth
36c00 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
36c10 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 function, or if
36c20 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
36c30 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 ng.** function p
36c40 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 arameter has cha
36c50 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d nged since the m
36c60 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 eta-data was set
36c70 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 ,.** then sqlite
36c80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
36c90 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
36ca0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
36cb0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
36cc0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
36cd0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 ce saves the met
36ce0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 adata.** pointed
36cf0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
36d00 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
36d10 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
36d20 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
36d30 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
36d40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
36d50 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 ction. Subseque
36d60 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
36d70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
36d80 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 ta() might retur
36d90 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 n this data, if
36da0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 it has.** not be
36db0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a en destroyed..**
36dc0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e ^If it is not N
36dd0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c ULL, SQLite will
36de0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
36df0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ructor.** functi
36e00 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 on given by the
36e10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
36e20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
36e30 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 data() on.** the
36e40 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 metadata when t
36e50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
36e60 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
36e70 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f ter changes.** o
36e80 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 r when the SQL s
36e90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 tatement complet
36ea0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f es, whichever co
36eb0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a mes first..**.**
36ec0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 SQLite is free
36ed0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 to call the dest
36ee0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 ructor and drop
36ef0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a metadata on any.
36f00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 ** parameter of
36f10 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 any function at
36f20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 any time. ^The
36f30 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 only guarantee i
36f40 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 s that.** the de
36f50 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 structor will be
36f60 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 called before t
36f70 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 he metadata is d
36f80 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ropped..**.** ^(
36f90 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
36fa0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 adata is preserv
36fb0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 ed between funct
36fc0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a ion calls for.**
36fd0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 expressions tha
36fe0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 t are constant a
36ff0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 t compile time.
37000 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 This includes li
37010 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 teral.** values
37020 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d and [parameters]
37030 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 .)^.**.** These
37040 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
37050 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
37060 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
37070 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
37080 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
37090 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
370a0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
370b0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_get_auxdata(sq
370c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
370d0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
370e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
370f0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
37100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
37110 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
37120 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
37130 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37140 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
37150 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
37160 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a uctor Behavior.*
37170 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
37180 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
37190 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
371a0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
371b0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
371c0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
371d0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
371e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
371f0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 b()]. ^If the d
37200 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
37210 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
37220 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
37230 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
37240 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
37250 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
37260 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
37270 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
37280 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
37290 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 d. ^The.** SQLI
372a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
372b0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
372c0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
372d0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
372e0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
372f0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
37300 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
37310 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
37320 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
37330 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
37340 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
37350 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
37360 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
37370 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
37380 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
37390 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 compilers. See
373a0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a ticket #2191..*
373b0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 /.typedef void (
373c0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 *sqlite3_destruc
373d0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 tor_type)(void*)
373e0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ;.#define SQLITE
373f0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 _STATIC ((s
37400 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
37410 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e r_type)0).#defin
37420 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 e SQLITE_TRANSIE
37430 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 NT ((sqlite3_d
37440 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d estructor_type)-
37450 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 1)../*.** CAPI3R
37460 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 EF: Setting The
37470 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c Result Of An SQL
37480 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 Function.**.**
37490 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
374a0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
374b0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
374c0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
374d0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
374e0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
374f0 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
37500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
37510 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
37520 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
37530 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
37540 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
37550 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
37560 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
37570 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
37580 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
37590 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
375a0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
375b0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
375c0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
375d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
375e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
375f0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
37600 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
37610 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
37620 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
37630 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
37640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
37650 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 e3_result_blob()
37660 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
37670 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a the result from.
37680 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ** an applicatio
37690 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
376a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f on to be the BLO
376b0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 B whose content
376c0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f is pointed.** to
376d0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
376e0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 arameter and whi
376f0 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f ch is N bytes lo
37700 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 ng where N is th
37710 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
37720 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
37730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37740 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 zeroblob() inter
37750 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 faces set the re
37760 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 sult of.** the a
37770 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
37780 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
37790 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e e a BLOB contain
377a0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 ing all zero.**
377b0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 bytes and N byte
377c0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 s in size, where
377d0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 N is the value
377e0 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d of the 2nd param
377f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 eter..**.** ^The
37800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37810 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 double() interfa
37820 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
37830 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 lt from.** an ap
37840 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37850 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
37860 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
37870 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 t value specifie
37880 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 d.** by its 2nd
37890 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
378a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
378b0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
378c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
378d0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f rror16() functio
378e0 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 ns.** cause the
378f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 implemented SQL
37900 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f function to thro
37910 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a w an exception..
37920 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
37930 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 the string point
37940 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 ed to by the.**
37950 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
37960 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37970 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 error() or sqlit
37980 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
37990 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 6().** as the te
379a0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d xt of an error m
379b0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 essage. ^SQLite
379c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
379d0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
379e0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
379f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37a00 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 r() as UTF-8. ^S
37a10 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 QLite.** interpr
37a20 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 ets the string f
37a30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 rom sqlite3_resu
37a40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 lt_error16() as
37a50 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
37a60 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 .** byte order.
37a70 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
37a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
37a90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37aa0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
37ab0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
37ac0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
37ad0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
37ae0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
37af0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
37b00 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
37b10 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
37b20 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
37b30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
37b40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
37b50 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a lt_error() or.**
37b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37b70 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e error16() is non
37b80 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 -negative then S
37b90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 QLite takes that
37ba0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 many.** bytes (
37bb0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 not characters)
37bc0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
37bd0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 ameter as the er
37be0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 ror message..**
37bf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
37c00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 ult_error() and
37c10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37c20 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 rror16().** rout
37c30 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 ines make a priv
37c40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
37c50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 error message te
37c60 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 xt before.** the
37c70 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 y return. Hence
37c80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 , the calling fu
37c90 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c nction can deall
37ca0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 ocate or.** modi
37cb0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 fy the text afte
37cc0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 r they return wi
37cd0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e thout harm..** ^
37ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
37cf0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 lt_error_code()
37d00 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 function changes
37d10 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a the error code.
37d20 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 ** returned by S
37d30 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c QLite as a resul
37d40 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e t of an error in
37d50 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 a function. ^B
37d60 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 y default,.** th
37d70 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 e error code is
37d80 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e SQLITE_ERROR. ^
37d90 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c A subsequent cal
37da0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 l to sqlite3_res
37db0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
37dc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
37dd0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 _error16() reset
37de0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
37df0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 to SQLITE_ERROR
37e00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37e10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37e20 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 r_toobig() inter
37e30 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
37e40 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a te to throw an.*
37e50 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 * error indicati
37e60 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 ng that a string
37e70 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 or BLOB is too
37e80 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e long to represen
37e90 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
37ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37eb0 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 or_nomem() inter
37ec0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 face causes SQLi
37ed0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a te to throw an.*
37ee0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 * error indicati
37ef0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 ng that a memory
37f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
37f10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
37f20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
37f30 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 t() interface se
37f40 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
37f50 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
37f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37f70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
37f80 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e the 32-bit sign
37f90 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
37fa0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
37fb0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
37fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
37fd0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e esult_int64() in
37fe0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
37ff0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
38000 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
38010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
38020 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 tion to be the 6
38030 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
38040 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 eger.** value gi
38050 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 ven in the 2nd a
38060 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
38070 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
38080 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 lt_null() interf
38090 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
380a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
380b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
380c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
380d0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a to be NULL..**.
380e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
380f0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 result_text(), s
38100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38110 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 xt16(),.** sqlit
38120 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
38130 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 le(), and sqlite
38140 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
38150 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
38160 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e * set the return
38170 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 value of the ap
38180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
38190 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
381a0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e .** a text strin
381b0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 g which is repre
381c0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c sented as UTF-8,
381d0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
381e0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 yte order,.** UT
381f0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 F-16 little endi
38200 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 an, or UTF-16 bi
38210 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 g endian, respec
38220 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 tively..** ^SQLi
38230 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
38240 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
38250 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
38260 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
38270 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
38280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38290 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
382a0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
382b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
382c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
382d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
382e0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
382f0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
38300 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 s result text fr
38310 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
38320 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 eter.** through
38330 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
38340 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 haracter..** ^If
38350 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
38360 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
38370 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
38380 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
38390 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
383a0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 en as many bytes
383b0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
383c0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a ) of the text.**
383d0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
383e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
383f0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 are taken as th
38400 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
38410 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f fined.** functio
38420 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 n result. If th
38430 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
38440 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
38450 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 then it.** must
38460 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
38470 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 set into the str
38480 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 ing where the NU
38490 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 L terminator wou
384a0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 ld.** appear if
384b0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 the string where
384c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e NUL terminated.
384d0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 If any NUL cha
384e0 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a racters occur.**
384f0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 in the string a
38500 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 t a byte offset
38510 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 that is less tha
38520 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 n the value of t
38530 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 he 3rd.** parame
38540 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ter, then the re
38550 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 sulting string w
38560 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 ill contain embe
38570 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 dded NULs and th
38580 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 e.** result of e
38590 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 xpressions opera
385a0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 ting on strings
385b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
385c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
385d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
385e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
385f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38600 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
38610 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
38620 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 esult_blob is a
38630 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
38640 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 , then SQLite ca
38650 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 lls that.** func
38660 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 tion as the dest
38670 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 ructor on the te
38680 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
38690 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a t when it has.**
386a0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
386b0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
386c0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
386d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
386e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
386f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 * interfaces or
38700 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 to.** sqlite3_re
38710 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
38720 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
38730 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c t SQLITE_STATIC,
38740 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 then SQLite.**
38750 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
38760 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 text or BLOB re
38770 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 sult is in const
38780 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f ant space and do
38790 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 es not.** copy t
387a0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
387b0 65 20 70 61 72