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 35 2e 20 20 ersion 3.7.15.
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 the individual
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 ation.** unit.
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 .** possible if
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 ly. Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 ion unit..**.**
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f pile SQLite. To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 , you need this
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 lite3.h" header
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 rary. (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 d within.** the
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 e. Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 de files may be
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 want a wrapper
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 ource code. In
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 **.** May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 evil..** May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 thers..** May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 y, never taking
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a ve..**.*********
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: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 upport on POSIX
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 t. If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 * Ticket #2739:
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 t appear before
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c ncludes. Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 ode must be the
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 ITE_DISABLE_LFS
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 d line. This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 achine (ex: Red
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 want your code
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c . If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 option, LFS is
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 enable. But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 does not exist
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 't work. Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 r Mac OS X. LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 ne _LARGE_FILE
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 1.# ifndef
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 S.# define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 eader output by
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 NFIG_H.#include
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 eLimit.h in the
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a liteLimit.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 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 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 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 BLOB in bytes.
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 LITE_MAX_LENGTH
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 ber of.**.**
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c able.** * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 .** * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 in a view.**
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 * Terms in the
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 t.** * Terms
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 atement.** *
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 .** * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 The hard upper
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 676. Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 lized database,
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e n any table. An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 d if.** that is
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 the case, there
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aving more than
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 alues in any of
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 gth of a single
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 used to be the
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 g this value to
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f . That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 nger true. It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 etime you might
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 ** A value of 0
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 But that is no
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 longer true. Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 rm. A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 o large. In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 rms. Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 codes in a VDBE
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 program..** Not
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 ndif../*.** The
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 * table and for
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 . The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 CHE_SIZE 2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 SIZE 500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ode..*/.#ifndef
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 TOCHECKPOINT 10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 ber of attached
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 databases. This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 0.** and 62. T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 n 62 is because
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 track attached
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 imum value of a
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 size. The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 r bound on this
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 value is 65536.
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 imposed by the
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 nger permitted,
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 is technically
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 ocess operating
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 s crashes, then
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 mit will not be
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 tion..*/.#ifdef
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 ULT_PAGE_SIZE.#
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 FAULT_PAGE_SIZE
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 ort),.** SQLite
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 ger value. This
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 constant is the
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 max_page_count
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 pragma..** This
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 cro..*/.#ifndef
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a mit.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 2f ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 c */.#endif../*
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 ers to integers
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 and.** integers
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 to pointers. Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 have developed
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 y to do this is
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 rs.** that vary
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d : The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 construct. But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 MSVC chokes on
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ys depending on
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 ) /* This case
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 should work for
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 GCC */.# define
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f R(X) ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 X) ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 __GNUC__)
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a _PTR(X) ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 _PTR_TO_INT(X)
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 STDINT_H) /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 se this case if
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 TR(X) ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 intptr_t)(X)).#
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 R_TO_INT(X) ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 ).#else
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 /* Generates a
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 _INT_TO_PTR(X)
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e _TO_INT(X) ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 e. 1 means the
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 ety. 2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 iple.** threads
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 threads try to
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 ion at the same
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 EADSAFE.#else.#
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61 f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20 fe overwrite is
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 on by default.
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65 But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74 d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45 he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f 0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41 f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64 FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57 efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41 The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61 ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20 ned as either 0
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65 or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72 r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76 MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75 ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20 lt or not. This
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20 value can.** be
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75 overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20 ntime using the
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46 fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66 * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65 acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69 o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74 tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 o use..**.**
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f ALLOC /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73 / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20 tem malloc().**
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 _MALLOC
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52 * SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 O_MALLOC
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75 // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44 SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20 EBUG
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20 // Debugging
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65 version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20 On Windows, if
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45 _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65 macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73 d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65 ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32 l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62 native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63 system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74 ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20 e to be called.
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74 If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72 will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65 rical note: The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65 re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69 veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20 * pared it down
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68 to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65 one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59 en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 OC) \. + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 ALLOC) \. + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 _MALLOC) \. + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64 ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65 but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53 is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33 LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22 ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 M_MALLOC) \. +
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57 defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 IN32_MALLOC) \.
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c . + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30 ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31 _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79 t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20 to keep the.**
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 sizes of memory
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65 w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20 LIMIT).# define
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65 FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58 eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66 OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20 ollows in order
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63 to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74 n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53 ems. But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53 .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75 OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72 ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65 Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20 told,.** so it
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65 is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72 673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20 XOPEN_SOURCE is
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72 poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73 nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f tems. So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61 id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69 t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65 s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77 needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69 e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20 ng a threadsafe
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23 build. Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2681..**.** See
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34 also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65 DARWIN__) && !de
3c10: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29 fined(__APPLE__)
3c20: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41 && SQLITE_THREA
3c30: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20 DSAFE.# define
3c40: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30 _XOPEN_SOURCE 50
3c50: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20 0 /* Needed to
3c60: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72 enable pthread r
3c70: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 ecursive mutexes
3c80: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a */.#endif../*.*
3c90: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72 * The TCL header
3ca0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65 s are only neede
3cb0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 d when compiling
3cc0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67 the TCL binding
3cd0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 s..*/.#if define
3ce0: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c d(SQLITE_TCL) ||
3cf0: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a defined(TCLSH).
3d00: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68 # include <tcl.h
3d10: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 >.#endif../*.**
3d20: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54 NDEBUG and SQLIT
3d30: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f E_DEBUG are oppo
3d40: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c sites. It shoul
3d50: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 d always be true
3d60: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64 that.** defined
3d70: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e (NDEBUG)==!defin
3d80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 ed(SQLITE_DEBUG)
3d90: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f . If this is no
3da0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65 t currently true
3db0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75 ,.** make it tru
3dc0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72 e by defining or
3dd0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42 undefining NDEB
3de0: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e UG..**.** Settin
3df0: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74 g NDEBUG makes t
3e00: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20 he code smaller
3e10: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62 and run faster b
3e20: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a y disabling the.
3e30: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74 ** number assert
3e40: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e () statements in
3e50: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77 the code. So w
3e60: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75 e want the defau
3e70: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 lt action.** to
3e80: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f be for NDEBUG to
3e90: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42 be set and NDEB
3ea0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e UG to be undefin
3eb0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54 ed only if SQLIT
3ec0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65 E_DEBUG.** is se
3ed0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20 t. Thus NDEBUG
3ee0: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69 becomes an opt-i
3ef0: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e n rather than an
3f00: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74 opt-out.** feat
3f10: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 ure..*/.#if !def
3f20: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20 ined(NDEBUG) &&
3f30: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f !defined(SQLITE_
3f40: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65 DEBUG) .# define
3f50: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66 NDEBUG 1.#endif
3f60: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45 .#if defined(NDE
3f70: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28 BUG) && defined(
3f80: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20 SQLITE_DEBUG).#
3f90: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e undef NDEBUG.#en
3fa0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 dif../*.** The t
3fb0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 estcase() macro
3fc0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69 is used to aid i
3fd0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 n coverage testi
3fe0: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f ng. When .** do
3ff0: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 ing coverage tes
4000: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74 ting, the condit
4010: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61 ion inside the a
4020: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 rgument to.** te
4030: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65 stcase() must be
4040: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20 evaluated both
4050: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69 true and false i
4060: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65 n order to.** ge
4070: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f t full branch co
4080: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73 verage. The tes
4090: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 tcase() macro is
40a0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20 inserted.** to
40b0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71 help ensure adeq
40c0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61 uate test covera
40d0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65 ge in places whe
40e0: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e re simple.** con
40f0: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 dition/decision
4100: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64 coverage is inad
4110: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61 equate. For exa
4120: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29 mple, testcase()
4130: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 .** can be used
4140: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75 to make sure bou
4150: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65 ndary values are
4160: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a tested. For.**
4170: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20 bitmask tests,
4180: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62 testcase() can b
4190: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 e used to make s
41a0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20 ure each bit.**
41b0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61 is significant a
41c0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74 nd used at least
41d0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63 once. On switc
41e0: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 h statements.**
41f0: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63 where multiple c
4200: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73 ases go to the s
4210: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 ame block of cod
4220: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a e, testcase().**
4230: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74 can insure that
4240: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65 all cases are e
4250: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a valuated..**.*/.
4260: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f #ifdef SQLITE_CO
4270: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49 VERAGE_TEST.SQLI
4280: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69 TE_PRIVATE voi
4290: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 d sqlite3Coverag
42a0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65 e(int);.# define
42b0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66 testcase(X) if
42c0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f ( X ){ sqlite3Co
42d0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 verage(__LINE__)
42e0: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 ; }.#else.# defi
42f0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23 ne testcase(X).#
4300: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
4310: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 TESTONLY macro
4320: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f is used to enclo
4330: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c se variable decl
4340: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f arations or.** o
4350: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64 ther bits of cod
4360: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65 e that are neede
4370: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65 d to support the
4380: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 arguments.** wi
4390: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20 thin testcase()
43a0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63 and assert() mac
43b0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 ros..*/.#if !def
43c0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20 ined(NDEBUG) ||
43d0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 defined(SQLITE_C
43e0: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20 OVERAGE_TEST).#
43f0: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 define TESTONLY(
4400: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 X) X.#else.# de
4410: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 fine TESTONLY(X)
4420: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 .#endif../*.** S
4430: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64 ometimes we need
4440: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 a small amount
4450: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20 of code such as
4460: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69 a variable initi
4470: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 alization.** to
4480: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65 setup for a late
4490: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 r assert() state
44a0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74 ment. We do not
44b0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20 want this code
44c0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65 to.** appear whe
44d0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69 n assert() is di
44e0: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c sabled. The fol
44f0: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20 lowing macro is
4500: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65 therefore.** use
4510: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61 d to contain tha
4520: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54 t setup code. T
4530: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d he "VVA" acronym
4540: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 stands for.** "
4550: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61 Verification, Va
4560: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63 lidation, and Ac
4570: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49 creditation". I
4580: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
4590: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69 he.** code withi
45a0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c n VVA_ONLY() wil
45b0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e l only run durin
45c0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70 g verification p
45d0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 rocesses..*/.#if
45e0: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65 ndef NDEBUG.# de
45f0: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 fine VVA_ONLY(X)
4600: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 X.#else.# defi
4610: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 ne VVA_ONLY(X).#
4620: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
4630: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 ALWAYS and NEVE
4640: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e R macros surroun
4650: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 d boolean expres
4660: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20 sions which .**
4670: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
4680: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f always be true o
4690: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74 r false, respect
46a0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20 ively. Such.**
46b0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c expressions coul
46c0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f d be omitted fro
46d0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c m the code compl
46e0: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79 etely. But they
46f0: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64 .** are included
4700: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20 in a few cases
4710: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61 in order to enha
4720: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e nce the resilien
4730: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 ce.** of SQLite
4740: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65 to unexpected be
4750: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 havior - to make
4760: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d the code "self-
4770: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 healing".** or "
4780: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20 ductile" rather
4790: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74 than being "brit
47a0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e tle" and crashin
47b0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a g at the first.*
47c0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e * hint of unplan
47d0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
47e0: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
47f0: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e ds, ALWAYS and N
4800: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66 EVER are added f
4810: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64 or defensive cod
4820: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f e..**.** When do
4830: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 ing coverage tes
4840: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20 ting ALWAYS and
4850: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63 NEVER are hard-c
4860: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72 oded to.** be tr
4870: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20 ue and false so
4880: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68 that the unreach
4890: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73 able code then s
48a0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e pecify will.** n
48b0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73 ot be counted as
48c0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a untested code..
48d0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 */.#if defined(S
48e0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 QLITE_COVERAGE_T
48f0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c EST).# define AL
4900: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29 WAYS(X) (1)
4910: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 .# define NEVER(
4920: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c X) (0).#el
4930: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 if !defined(NDEB
4940: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 UG).# define ALW
4950: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29 AYS(X) ((X)
4960: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29 ?1:(assert(0),0)
4970: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 ).# define NEVER
4980: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28 (X) ((X)?(
4990: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a assert(0),1):0).
49a0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41 #else.# define A
49b0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58 LWAYS(X) (X
49c0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 ).# define NEVER
49d0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65 (X) (X).#e
49e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 ndif../*.** Retu
49f0: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 rn true (non-zer
4a00: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 o) if the input
4a10: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61 is a integer tha
4a20: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a t is too large.*
4a30: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62 * to fit in 32-b
4a40: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f its. This macro
4a50: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20 is used inside
4a60: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63 of various testc
4a70: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 ase().** macros
4a80: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77 to verify that w
4a90: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51 e have tested SQ
4aa0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66 Lite for large-f
4ab0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a ile support..*/.
4ac0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49 #define IS_BIG_I
4ad0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69 NT(X) (((X)&~(i
4ae0: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d 64)0xffffffff)!=
4af0: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 0)../*.** The ma
4b00: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69 cro unlikely() i
4b10: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75 s a hint that su
4b20: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61 rrounds a boolea
4b30: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
4b40: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 that is usually
4b50: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69 false. Macro li
4b60: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73 kely() surrounds
4b70: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78 .** a boolean ex
4b80: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73 pression that is
4b90: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20 usually true.
4ba0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a GCC is able to.*
4bb0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74 * use these hint
4bc0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65 s to generate be
4bd0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74 tter code, somet
4be0: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 imes..*/.#if def
4bf0: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 ined(__GNUC__) &
4c00: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b & 0.# define lik
4c10: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c ely(X) __buil
4c20: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31 tin_expect((X),1
4c30: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b ).# define unlik
4c40: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69 ely(X) __builti
4c50: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a n_expect((X),0).
4c60: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c #else.# define l
4c70: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58 ikely(X) !!(X
4c80: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b ).# define unlik
4c90: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65 ely(X) !!(X).#e
4ca0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ndif../*********
4cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 ***** Include sq
4cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d lite3.h in the m
4cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 iddle of sqliteI
4ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
4cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ****/./*********
4d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 ***** Begin file
4d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a sqlite3.h *****
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 ****/./*.** 2001
4d50: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a September 15.**
4d60: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 .** The author d
4d70: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 isclaims copyrig
4d80: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 ht to this sourc
4d90: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 e code. In plac
4da0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 e of.** a legal
4db0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 notice, here is
4dc0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a a blessing:.**.*
4dd0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 * May you do
4de0: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 good and not evi
4df0: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 l..** May you
4e00: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 find forgivenes
4e10: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 s for yourself a
4e20: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 nd forgive other
4e30: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 s..** May you
4e40: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e share freely, n
4e50: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 ever taking more
4e60: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a than you give..
4e70: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **.*************
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 ************.**
4ec0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 This header file
4ed0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
4ee0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 erface that the
4ef0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a SQLite library.*
4f00: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c * presents to cl
4f10: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 ient programs.
4f20: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c If a C-function,
4f30: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 structure, data
4f40: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 type,.** or cons
4f50: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 tant definition
4f60: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 does not appear
4f70: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 in this file, th
4f80: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 en it is.** not
4f90: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 a published API
4fa0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 of SQLite, is su
4fb0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
4fc0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 without.** notic
4fd0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f e, and should no
4fe0: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 t be referenced
4ff0: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 by programs that
5000: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a use SQLite..**.
5010: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 ** Some of the d
5020: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 efinitions that
5030: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 are in this file
5040: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a are marked as.*
5050: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 * "experimental"
5060: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 . Experimental
5070: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
5080: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 ormally new.** f
5090: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 eatures recently
50a0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 added to SQLite
50b0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 . We do not ant
50c0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a icipate changes.
50d0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 ** to experiment
50e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 al interfaces bu
50f0: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69 t reserve the ri
5100: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f ght to make mino
5110: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 r changes.** if
5120: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
5130: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
5140: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
5150: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
5160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
5170: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
5180: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
5190: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
51a0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
51b0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
51c0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
51d0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
51e0: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
51f0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
5200: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
5210: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
5220: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
5230: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
5240: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
5250: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
5260: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
5270: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
5280: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
5290: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
52a0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
52b0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
52c0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
52d0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
52e0: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
52f0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
5300: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
5310: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 cess..*/.#ifndef
5320: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 _SQLITE3_H_.#de
5330: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f fine _SQLITE3_H_
5340: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
5350: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
5360: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
5370: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
5380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
5390: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
53a0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
53b0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 C++..*/.#if 0.e
53c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
53d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 if.../*.** Add t
53e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 he ability to ov
53f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a erride 'extern'.
5400: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
5410: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e E_EXTERN.# defin
5420: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 e SQLITE_EXTERN
5430: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 extern.#endif..#
5440: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 ifndef SQLITE_AP
5450: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
5460: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f E_API.#endif.../
5470: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 *.** These no-op
5480: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 macros are used
5490: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 in front of int
54a0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 erfaces to mark
54b0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 those.** interfa
54c0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 ces as either de
54d0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 precated or expe
54e0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 rimental. New a
54f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
5500: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 hould not use de
5510: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 precated interfa
5520: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 ces - they are s
5530: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 upport for backw
5540: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
5550: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 ility only. App
5560: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 lication writers
5570: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 should be aware
5580: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d that.** experim
5590: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
55a0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 are subject to
55b0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 change in point
55c0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
55d0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 These macros use
55e0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 d to resolve to
55f0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 various kinds of
5600: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
5610: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 that.** would ge
5620: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d nerate warning m
5630: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 essages when the
5640: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 y were used. Bu
5650: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c t that.** compil
5660: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 er magic ended u
5670: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 p generating suc
5680: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 h a flurry of bu
5690: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 g reports.** tha
56a0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 t we have taken
56b0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 it all out and g
56c0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e one back to usin
56d0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 g simple.** noop
56e0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 macros..*/.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 ine SQLITE_DEPRE
5700: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 CATED.#define SQ
5710: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
5720: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 L../*.** Ensure
5730: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 these symbols we
5740: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 re not defined b
5750: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 y some previous
5760: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a header file..*/.
5770: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 #ifdef SQLITE_VE
5780: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 RSION.# undef SQ
5790: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e LITE_VERSION.#en
57a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
57b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
57c0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
57d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
57e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
57f0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
5800: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
5810: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a ion Numbers.**.*
5820: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f * ^(The [SQLITE_
5830: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 VERSION] C prepr
5840: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e ocessor macro in
5850: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 the sqlite3.h h
5860: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 eader.** evaluat
5870: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c es to a string l
5880: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 iteral that is t
5890: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f he SQLite versio
58a0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d n in the.** form
58b0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 at "X.Y.Z" where
58c0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 X is the major
58d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 version number (
58e0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 always 3 for.**
58f0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 SQLite3) and Y i
5900: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 s the minor vers
5910: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a ion number and Z
5920: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 is the release
5930: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 number.)^.** ^(T
5940: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
5950: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 ON_NUMBER] C pre
5960: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
5970: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 resolves to an i
5980: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 nteger.** with t
5990: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 he value (X*1000
59a0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 000 + Y*1000 + Z
59b0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e ) where X, Y, an
59c0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 d Z are the same
59d0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 .** numbers used
59e0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 in [SQLITE_VERS
59f0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 ION].)^.** The S
5a00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
5a10: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 MBER for any giv
5a20: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 en release of SQ
5a30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a Lite will also.*
5a40: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e * be larger than
5a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f the release fro
5a60: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 m which it is de
5a70: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 rived. Either Y
5a80: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 will.** be held
5a90: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 constant and Z
5aa0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e will be incremen
5ab0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 ted or else Y wi
5ac0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
5ad0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 d.** and Z will
5ae0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f be reset to zero
5af0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 ..**.** Since ve
5b00: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 rsion 3.6.18, SQ
5b10: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 Lite source code
5b20: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 has been stored
5b30: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 in the.** <a hr
5b40: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 ef="http://www.f
5b50: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e ossil-scm.org/">
5b60: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 Fossil configura
5b70: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a tion management.
5b80: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 ** system</a>.
5b90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 ^The SQLITE_SOUR
5ba0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c CE_ID macro eval
5bb0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 uates to.** a st
5bc0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 ring which ident
5bd0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c ifies a particul
5be0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 ar check-in of S
5bf0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 QLite.** within
5c00: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f its configuratio
5c10: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 n management sys
5c20: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 tem. ^The SQLIT
5c30: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 E_SOURCE_ID.** s
5c40: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 tring contains t
5c50: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 he date and time
5c60: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e of the check-in
5c70: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 (UTC) and an SH
5c80: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 A1.** hash of th
5c90: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 e entire source
5ca0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tree..**.** See
5cb0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c also: [sqlite3_l
5cc0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a ibversion()],.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
5ce0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 sion_number()],
5cf0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 [sqlite3_sourcei
5d00: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
5d10: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
5d20: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
5d30: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 d()]..*/.#define
5d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 SQLITE_VERSION
5d50: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 35 22 0a "3.7.15".
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
5d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 ERSION_NUMBER 30
5d80: 30 37 30 31 35 0a 23 64 65 66 69 6e 65 20 53 51 07015.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 LITE_SOURCE_ID
5da0: 20 20 20 20 22 32 30 31 32 2d 30 39 2d 31 32 20 "2012-09-12
5db0: 30 30 3a 31 31 3a 32 30 20 39 34 30 32 66 38 31 00:11:20 9402f81
5dc0: 66 61 64 65 35 66 63 61 65 30 61 33 61 36 65 66 fade5fcae0a3a6ef
5dd0: 64 63 37 61 35 63 64 66 37 31 66 63 32 65 37 39 dc7a5cdf71fc2e79
5de0: 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 f"../*.** CAPI3R
5df0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
5e00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
5e10: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 bers.** KEYWORDS
5e20: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f : sqlite3_versio
5e30: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 n, sqlite3_sourc
5e40: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 eid.**.** These
5e50: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 interfaces provi
5e60: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f de the same info
5e70: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b rmation as the [
5e80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c SQLITE_VERSION],
5e90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
5ea0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 ION_NUMBER], and
5eb0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
5ec0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
5ed0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 or macros.** but
5ee0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 are associated
5ef0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
5f00: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
5f10: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 header file. ^(
5f20: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 Cautious.** prog
5f30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e rammers might in
5f40: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 clude assert() s
5f50: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
5f60: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
5f70: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 o.** verify that
5f80: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
5f90: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 by these interf
5fa0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d aces match the m
5fb0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 acros in.** the
5fc0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 header, and thus
5fd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 insure that the
5fe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a application is.
5ff0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
6000: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 matching librar
6010: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c y and header fil
6020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b es..**.** <block
6030: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 quote><pre>.** a
6040: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c ssert( sqlite3_l
6050: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
6060: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 ()==SQLITE_VERSI
6070: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 ON_NUMBER );.**
6080: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
6090: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
60a0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f ),SQLITE_SOURCE_
60b0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 ID)==0 );.** ass
60c0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 ert( strcmp(sqli
60d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
60e0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 ,SQLITE_VERSION)
60f0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ==0 );.** </pre>
6100: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
6110: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
6120: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
6130: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
6140: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
6150: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f f [SQLITE_VERSIO
6160: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 N].** macro. ^T
6170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
6180: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
6190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
61a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 er to the.** to
61b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
61c0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
61d0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 stant. The sqli
61e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
61f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
6200: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 provided for use
6210: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 in DLLs since D
6220: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 LL users usually
6230: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 do not have.**
6240: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
6250: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
6260: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c s within the DLL
6270: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
6280: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
6290: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 mber() function
62a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
62b0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b er equal to.** [
62c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
62d0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 UMBER]. ^The sq
62e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
62f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
6300: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
6310: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
6320: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 tant whose value
6330: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
6340: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
6350: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
6360: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e processor macro.
6370: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
6380: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e [sqlite_version
6390: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f ()] and [sqlite_
63a0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f source_id()]..*/
63b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
63c0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 t char sqlite3_v
63d0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 ersion[] = SQLIT
63e0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 E_VERSION;.SQLIT
63f0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
6400: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 *sqlite3_libver
6410: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 sion(void);.SQLI
6420: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
6430: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
6440: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 eid(void);.SQLIT
6450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
6460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
6470: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ber(void);../*.*
6480: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
6490: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d Time Library Com
64a0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 pilation Options
64b0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a Diagnostics.**.
64c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
64d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
64e0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 ed() function re
64f0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a turns 0 or 1 .**
6500: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 indicating whet
6510: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 her the specifie
6520: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 d option was def
6530: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 ined at .** comp
6540: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 ile time. ^The
6550: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d SQLITE_ prefix m
6560: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 ay be omitted fr
6570: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f om the .** optio
6580: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f n name passed to
6590: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
65a0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 option_used().
65b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
65c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
65d0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e n_get() function
65e0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e allows iteratin
65f0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 g.** over the li
6600: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 st of options th
6610: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 at were defined
6620: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 at compile time
6630: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 by.** returning
6640: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 the N-th compile
6650: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 time option str
6660: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f ing. ^If N is o
6670: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 ut of range,.**
6680: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
6690: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 ption_get() retu
66a0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
66b0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 er. ^The SQLITE
66c0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 _ .** prefix is
66d0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 omitted from any
66e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
66f0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d by .** sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
6710: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 et()..**.** ^Sup
6720: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 port for the dia
6730: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e gnostic function
6740: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c s sqlite3_compil
6750: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a eoption_used().*
6760: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
6770: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
6780: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 ) may be omitted
6790: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 by specifying t
67a0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
67b0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f MIT_COMPILEOPTIO
67c0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 N_DIAGS] option
67d0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
67e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
67f0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b SQL functions [
6800: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 sqlite_compileop
6810: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 tion_used()] and
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 .** [sqlite_comp
6830: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d ileoption_get()]
6840: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c and the [compil
6850: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 e_options pragma
6860: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 ]..*/.#ifndef SQ
6870: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
6880: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 EOPTION_DIAGS.SQ
6890: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
68a0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
68b0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 on_used(const ch
68c0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 ar *zOptName);.S
68d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
68e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
68f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
6900: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6920: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
6930: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
6940: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
6950: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
6960: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
6970: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
6980: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
6990: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
69a0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
69b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
69c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
69d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
69e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
69f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
6a00: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
6a10: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
6a20: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
6a30: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
6a40: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
6a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
6a60: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
6a70: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
6a80: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
6a90: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
6aa0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
6ab0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
6ac0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
6ad0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
6ae0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
6af0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
6b00: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
6b10: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
6b20: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
6b30: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
6b40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
6b50: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
6b60: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
6b70: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
6b80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
6b90: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
6ba0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
6bb0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
6bc0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
6bd0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
6be0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
6bf0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
6c00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
6c10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
6c20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
6c30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
6c40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
6c50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
6c60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
6c70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
6c80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
6c90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
6ca0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
6cb0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
6cc0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
6cd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
6ce0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
6cf0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
6d00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
6d10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
6d20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
6d30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
6d40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
6d50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
6d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
6d70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
6d80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
6d90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
6da0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
6db0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
6dc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
6dd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
6de0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
6df0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
6e00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
6e10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
6e20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
6e30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
6e40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
6e50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
6e60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
6e70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
6e80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
6e90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
6ea0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
6eb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
6ec0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
6ed0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
6ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
6ef0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
6f00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
6f10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
6f20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
6f30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
6f40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
6f50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
6f60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
6f70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
6f80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
6f90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
6fa0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
6fb0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
6fc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
6fd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
6fe0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
6ff0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
7000: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
7010: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
7020: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
7030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
7040: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
7050: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
7060: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
7070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
7080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7090: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
70a0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
70b0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
70c0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
70d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
70e0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
70f0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
7100: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
7110: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
7120: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
7130: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
7140: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
7150: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
7160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
7170: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
7180: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
7190: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
71a0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
71b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
71c0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 se()].** and [sq
71d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
71e0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 ] are its destru
71f0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 ctors. There ar
7200: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 e many other.**
7210: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 interfaces (such
7220: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f as.** [sqlite3_
7230: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
7240: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
7250: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a unction()], and.
7260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
7270: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e _timeout()] to n
7280: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 ame but three) t
7290: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 hat are methods
72a0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 on an.** sqlite3
72b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 object..*/.type
72c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
72d0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a e3 sqlite3;../*.
72e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
72f0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
7300: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 s.** KEYWORDS: s
7310: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
7320: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
7330: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
7340: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
7350: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
7360: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
7370: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
7380: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
7390: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
73a0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
73b0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
73c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
73d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
73e0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
73f0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
7400: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
7410: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
7420: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
7430: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
7440: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
7450: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
7460: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
7470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
7480: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 64 and sqlite_in
7490: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 t64 types can st
74a0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ore integer valu
74b0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 es.** between -9
74c0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
74d0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 08 and +92233720
74e0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 36854775807 incl
74f0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 usive. ^The.**
7500: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 sqlite3_uint64 a
7510: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
7520: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
7530: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
7540: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e .** between 0 an
7550: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 d +1844674407370
7560: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 9551615 inclusiv
7570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
7580: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 ITE_INT64_TYPE.
7590: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
75a0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
75b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
75c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 ef unsigned SQLI
75d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
75e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
75f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f if defined(_MSC_
7600: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 VER) || defined(
7610: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 __BORLANDC__).
7620: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 typedef __int64
7630: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
7640: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
7650: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
7660: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 uint64;.#else.
7670: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e typedef long lon
7680: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 g int 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 6c 6f 6e 67 20 6c 6f 6e 67 signed long long
76b0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 int sqlite_uint
76c0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 64;.#endif.typed
76d0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 ef sqlite_int64
76e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 sqlite3_int64;.t
76f0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 ypedef sqlite_ui
7700: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e nt64 sqlite3_uin
7710: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 t64;../*.** If c
7720: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 ompiling for a p
7730: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 rocessor that la
7740: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 cks floating poi
7750: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 nt support,.** s
7760: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 ubstitute intege
7770: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 r for floating-p
7780: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 oint..*/.#ifdef
7790: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 SQLITE_OMIT_FLOA
77a0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 TING_POINT.# def
77b0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 ine double sqlit
77c0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a e3_int64.#endif.
77d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
77e0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 Closing A Datab
77f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
7800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
7810: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 3_close() and sq
7820: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
7830: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
7840: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 structors.** for
7850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
7860: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 bject..** ^Calls
7870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to sqlite3_clos
7880: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
7890: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 close_v2() retur
78a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a n SQLITE_OK if.*
78b0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 * the [sqlite3]
78c0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 object is succes
78d0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 sfully destroyed
78e0: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 and all associa
78f0: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ted.** resources
7900: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 are deallocated
7910: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
7920: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
7930: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 ion is associate
7940: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
7950: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 ed prepared.** s
7960: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 tatements or unf
7970: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
7980: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 backup objects t
7990: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 hen sqlite3_clos
79a0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 e().** will leav
79b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
79c0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 onnection open a
79d0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
79e0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 E_BUSY]..** ^If
79f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
7a00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
7a10: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 h unfinalized pr
7a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
7a30: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73 s.** and unfinis
7a40: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b hed sqlite3_back
7a50: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ups, then the da
7a60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7a70: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 n becomes.** an
7a80: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 unusable "zombie
7a90: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 " which will aut
7aa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 omatically be de
7ab0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 allocated when t
7ac0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 he.** last prepa
7ad0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
7ae0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 finalized or th
7af0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 e last sqlite3_b
7b00: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 ackup is.** fini
7b10: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 shed. The sqlit
7b20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e e3_close_v2() in
7b30: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e terface is inten
7b40: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 ded for use with
7b50: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 .** host languag
7b60: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 es that are garb
7b70: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 age collected, a
7b80: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 nd where the ord
7b90: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 er in which.** d
7ba0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 estructors are c
7bb0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 alled is arbitra
7bc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ry..**.** Applic
7bd0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 ations should [s
7be0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
7bf0: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 | finalize] all
7c00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
7c10: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ents],.** [sqlit
7c20: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
7c30: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
7c40: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a handles], and .
7c50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
7c60: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 up_finish | fini
7c70: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 sh] all [sqlite3
7c80: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
7c90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
7ca0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
7cb0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 ] object prior t
7cc0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 o attempting to
7cd0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 close the object
7ce0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 . ^If.** sqlite
7cf0: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 3_close() is cal
7d00: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
7d20: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
7d30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
7d40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
7d50: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
7d60: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
7d70: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
7d80: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
7d90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
7da0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63 but the dealloc
7db0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f ation.** of reso
7dc0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 urces is deferre
7dd0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 d until all [pre
7de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
7df0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 ], [BLOB handles
7e00: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 ],.** and [sqlit
7e10: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
7e20: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 ts are also dest
7e30: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 royed..**.** ^If
7e40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 an [sqlite3] ob
7e50: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 ject is destroye
7e60: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 d while a transa
7e70: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a ction is open,.*
7e80: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f * the transactio
7e90: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c n is automatical
7ea0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
7eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 **.** The C para
7ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
7ed0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 3_close(C)] and
7ee0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 [sqlite3_close_v
7ef0: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 2(C)].** must be
7f00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a either a NULL.*
7f10: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 * pointer or an
7f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
7f30: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 pointer obtaine
7f40: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
7f50: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
7f60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
7f70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
7f80: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e pen_v2()], and n
7f90: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c ot previously cl
7fa0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e osed..** ^Callin
7fb0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 g sqlite3_close(
7fc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f ) or sqlite3_clo
7fd0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e se_v2() with a N
7fe0: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 ULL pointer.** a
7ff0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 rgument is a har
8000: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
8010: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
8020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
8030: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
8040: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
8050: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
8060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
8070: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
8080: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
8090: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
80a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
80b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
80c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
80d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
80e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
80f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
8100: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
8110: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
8120: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
8130: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
8140: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
8150: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
8160: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 erface.**.** The
8170: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8180: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 interface is a c
8190: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 onvenience wrapp
81a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
81b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
81c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
81d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
81e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c te3_finalize()],
81f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 .** that allows
8200: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
8210: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 o run multiple s
8220: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c tatements of SQL
8230: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 .** without havi
8240: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 ng to use a lot
8250: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a of C code. .**.*
8260: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
8270: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
8280: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 runs zero or mor
8290: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c e UTF-8 encoded,
82a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
82b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 parate SQL state
82c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
82d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 o its 2nd argume
82e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f nt,.** in the co
82f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
8300: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
8310: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 n] passed in as
8320: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d its 1st.** argum
8330: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ent. ^If the ca
8340: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
8350: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d of the 3rd argum
8360: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ent to.** sqlite
8370: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
8380: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 NULL, then it is
8390: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 invoked for eac
83a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 h result row.**
83b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 coming out of th
83c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 e evaluated SQL
83d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 statements. ^Th
83e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
83f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
8400: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 c() is relayed t
8410: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 hrough to the 1s
8420: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 t argument of ea
8430: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ch.** callback i
8440: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 nvocation. ^If
8450: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 the callback poi
8460: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f nter to sqlite3_
8470: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c exec().** is NUL
8480: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 L, then no callb
8490: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f ack is ever invo
84a0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 ked and result r
84b0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 ows are.** ignor
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ed..**.** ^If an
84d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
84e0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 ile evaluating t
84f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
8500: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a s passed into.**
8510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c sqlite3_exec(),
8520: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 then execution
8530: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 of the current s
8540: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 tatement stops a
8550: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 nd.** subsequent
8560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
8570: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 skipped. ^If th
8580: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
8590: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
85a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ).** is not NULL
85b0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 then any error
85c0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 message is writt
85d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
85e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
85f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
8600: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 )] and passed ba
8610: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ck through the 5
8620: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a th parameter..**
8630: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 To avoid memory
8640: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c leaks, the appl
8650: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 ication should i
8660: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
8670: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 ree()].** on err
8680: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
8690: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f gs returned thro
86a0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
86b0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 meter of.** of s
86c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
86d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
86e0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
86f0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
8700: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
8710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
8720: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
8730: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
8740: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
8750: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
8760: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
8770: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
8780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
8790: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
87a0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
87b0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
87c0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
87d0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
87e0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
87f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
8800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
8810: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
8820: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
8830: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
8840: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
8850: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
8860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
8870: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
8880: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
8890: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
88a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
88b0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
88c0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
88d0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
88e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
88f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
8900: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
8910: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
8920: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
8930: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
8940: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
8950: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
8960: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
8970: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
8980: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
8990: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
89a0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
89b0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
89c0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
89d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
89e0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
89f0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
8a00: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
8a10: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
8a20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
8a30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
8a40: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
8a50: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
8a60: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
8a70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
8a80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
8a90: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
8aa0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
8ab0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
8ac0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
8ad0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
8ae0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
8af0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
8b00: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
8b10: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
8b20: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
8b30: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
8b40: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
8b50: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
8b60: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
8b70: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
8b80: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
8b90: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
8ba0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
8bb0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
8bc0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
8bd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
8be0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8bf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 t insure that th
8c00: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
8c10: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
8c20: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
8c30: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
8c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
8c50: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
8c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8c70: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 t not close [dat
8c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
8c90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
8ca0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
8cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
8cc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
8cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8ce0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
8cf0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
8d00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
8d10: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
8d20: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
8d30: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
8d40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
8d50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
8d60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
8d70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
8d80: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
8d90: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
8da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
8db0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
8de0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
8df0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
8e00: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
8e20: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
8e30: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
8e40: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
8e50: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
8e60: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
8e70: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
8e80: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
8eb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
8ec0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
8ed0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8ef0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
8f00: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
8f10: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
8f20: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
8f30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
8f40: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f SQLITE_OK {erro
8f50: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 r code} {error c
8f60: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 odes}.** KEYWORD
8f70: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d S: {result code}
8f80: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a {result codes}.
8f90: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
8fa0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
8fb0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
8fc0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
8fd0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
8fe0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
8ff0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 indicate succes
9000: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a s or failure..**
9010: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f .** New error co
9020: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 des may be added
9030: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
9040: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
9050: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
9060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
9070: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 D | extended res
9080: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b ult codes],.** [
9090: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f sqlite3_vtab_on_
90a0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c conflict()] [SQL
90b0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 ITE_ROLLBACK | r
90c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f esult codes]..*/
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
90e0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 OK 0
90f0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 /* Successful r
9100: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 esult */./* begi
9110: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 nning-of-error-c
9120: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 odes */.#define
9130: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 SQLITE_ERROR
9140: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 1 /* SQL e
9150: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 rror or missing
9160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
9180: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 NAL 2 /* I
9190: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 nternal logic er
91a0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f ror in SQLite */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
91c0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 PERM 3
91d0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 /* Access permi
91e0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ssion denied */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
9200: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 BORT 4
9210: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 /* Callback rout
9220: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e ine requested an
9230: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e abort */.#defin
9240: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 e SQLITE_BUSY
9250: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 5 /* The
9260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
9270: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
9280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
9290: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 D 6 /* A
92a0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 table in the da
92b0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 tabase is locked
92c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
92d0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 TE_NOMEM
92e0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 7 /* A malloc(
92f0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 ) failed */.#def
9300: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
9310: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 NLY 8 /* A
9320: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 ttempt to write
9330: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 a readonly datab
9340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
9350: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 QLITE_INTERRUPT
9360: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 9 /* Operat
9370: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 ion terminated b
9380: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 y sqlite3_interr
9390: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 upt()*/.#define
93a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 SQLITE_IOERR
93b0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 10 /* Some
93c0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f kind of disk I/O
93d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 error occurred
93e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
93f0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 E_CORRUPT 11
9400: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
9410: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 se disk image is
9420: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 malformed */.#d
9430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
9440: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a FOUND 12 /*
9450: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 Unknown opcode
9460: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f in sqlite3_file_
9470: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 control() */.#de
9480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c fine SQLITE_FULL
9490: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 13 /*
94a0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 Insertion failed
94b0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 because databas
94c0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 e is full */.#de
94d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
94e0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 OPEN 14 /*
94f0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 Unable to open t
9500: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
9520: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 TE_PROTOCOL 1
9530: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
9540: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
9550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
9560: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
9570: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
9580: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
9590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
95a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
95b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
95c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
95d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
95e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
95f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
9600: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
9610: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
9620: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
9630: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
9640: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 t due to constra
9650: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f int violation */
9660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9670: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 MISMATCH 20
9680: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 /* Data type mi
9690: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e smatch */.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 e SQLITE_MISUSE
96b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 21 /* Lib
96c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 rary used incorr
96d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ectly */.#define
96e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 SQLITE_NOLFS
96f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 22 /* Uses
9700: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 OS features not
9710: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f supported on ho
9720: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
9730: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 LITE_AUTH
9740: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 23 /* Authori
9750: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f zation denied */
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9770: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 FORMAT 24
9780: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 /* Auxiliary da
9790: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 tabase format er
97a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
97b0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 QLITE_RANGE
97c0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 25 /* 2nd pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
97e0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 e3_bind out of r
97f0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ange */.#define
9800: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 SQLITE_NOTADB
9810: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 26 /* File
9820: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e opened that is n
9830: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 ot a database fi
9840: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
9850: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
9860: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
9870: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
9880: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
9890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
98a0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
98b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
98c0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
98d0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
98e0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
98f0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
9900: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
9910: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
9920: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
9930: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
9940: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
9950: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
9960: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
9970: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
9980: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9990: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
99a0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
99b0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
99c0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
99d0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
99e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
99f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
9a00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
9a10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
9a20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
9a30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
9a40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
9a50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
9a60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
9a70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
9a80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
9a90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
9aa0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
9ab0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
9ac0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
9ad0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
9ae0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
9af0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
9b00: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
9b10: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
9b20: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
9b30: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
9b40: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
9b50: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
9b60: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
9b70: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
9b80: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
9b90: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
9ba0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
9bb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9bc0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
9bd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
9be0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
9bf0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
9c00: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
9c10: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
9c20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
9c30: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
9c40: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
9c50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
9c60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
9c70: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
9c80: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
9c90: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
9ca0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
9cb0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
9cc0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
9cd0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
9ce0: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
9cf0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
9d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
9d10: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
9d20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
9d30: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
9d40: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
9d50: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
9d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9d70: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
9d80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9d90: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a IOERR | (1<<8)).
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
9db0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
9dc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
9dd0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9df0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9e10: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
9e30: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
9e50: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
9e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
9e70: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
9e80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
9e90: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 R | (5<<8)).#def
9ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
9eb0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 _TRUNCATE
9ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
9ed0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
9ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
9ef0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 FSTAT
9f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
9f10: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
9f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
9f30: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 NLOCK
9f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
9f50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
9f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
9f70: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
9f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9f90: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
9fb0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 ETE (
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
9fd0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
9ff0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 CKED (
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a010: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 11<<8)).#define
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d SQLITE_IOERR_NOM
a030: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 EM (
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a050: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 12<<8)).#define
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
a070: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 ESS (
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a090: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 13<<8)).#define
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 SQLITE_IOERR_CHE
a0b0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 CKRESERVEDLOCK (
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a0d0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 14<<8)).#define
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 SQLITE_IOERR_LOC
a0f0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a110: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 15<<8)).#define
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f SQLITE_IOERR_CLO
a130: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 SE (
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a150: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 16<<8)).#define
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
a170: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 _CLOSE (
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a190: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 17<<8)).#define
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a1b0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 OPEN (
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a1d0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 18<<8)).#define
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a1f0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 SIZE (
a200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a210: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 19<<8)).#define
a220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a230: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 LOCK (
a240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a250: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 20<<8)).#define
a260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a270: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 MAP (
a280: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a290: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 21<<8)).#define
a2a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 SQLITE_IOERR_SEE
a2b0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
a2c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a2d0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 22<<8)).#define
a2e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
a2f0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
a300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
a310: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
a320: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
a330: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
a340: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
a350: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
a360: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
a370: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
a380: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
a390: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
a3a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
a3b0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
a3c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
a3d0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
a3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
a3f0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 RUPT_VTAB
a400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 (SQLITE_COR
a410: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 RUPT | (1<<8)).#
a420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
a430: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 ADONLY_RECOVERY
a440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
a450: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 ADONLY | (1<<8))
a460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a470: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 READONLY_CANTLOC
a480: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f K (SQLITE_
a490: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 READONLY | (2<<8
a4a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a4b0: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b E_ABORT_ROLLBACK
a4c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
a4d0: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 E_ABORT | (2<<8)
a4e0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
a4f0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
a500: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
a510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 s.**.** These bi
a520: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 t values are int
a530: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
a540: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 the.** 3rd para
a550: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
a560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
a570: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a interface and.*
a580: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 * in the 4th par
a590: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
a5a0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
a5b0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 ] method..*/.#de
a5c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a5d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 _READONLY
a5e0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 0x00000001 /*
a5f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
a600: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
a610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a620: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 _READWRITE
a630: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 0x00000002 /*
a640: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
a650: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
a660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a670: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 _CREATE
a680: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 0x00000004 /*
a690: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
a6a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
a6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a6c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 _DELETEONCLOSE
a6d0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 0x00000008 /*
a6e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a6f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a700: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 _EXCLUSIVE
a710: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 0x00000010 /*
a720: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a740: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 _AUTOPROXY
a750: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 0x00000020 /*
a760: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a780: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 _URI
a790: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 0x00000040 /*
a7a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
a7b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
a7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a7d0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 _MEMORY
a7e0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 0x00000080 /*
a7f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
a800: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
a810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a820: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 _MAIN_DB
a830: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 0x00000100 /*
a840: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a860: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 _TEMP_DB
a870: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 0x00000200 /*
a880: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a8a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 _TRANSIENT_DB
a8b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 0x00000400 /*
a8c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a8e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 _MAIN_JOURNAL
a8f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 0x00000800 /*
a900: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a920: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 _TEMP_JOURNAL
a930: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 0x00001000 /*
a940: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a960: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 _SUBJOURNAL
a970: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 0x00002000 /*
a980: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a9a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 _MASTER_JOURNAL
a9b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 0x00004000 /*
a9c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
a9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
a9e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 _NOMUTEX
a9f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 0x00008000 /*
aa00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
aa10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
aa30: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 _FULLMUTEX
aa40: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 0x00010000 /*
aa50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
aa60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
aa70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
aa80: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 _SHAREDCACHE
aa90: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 0x00020000 /*
aaa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
aab0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
aac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
aad0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 _PRIVATECACHE
aae0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 0x00040000 /*
aaf0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
ab00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
ab10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
ab20: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
ab30: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 0x00080000 /*
ab40: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a VFS only */../*
ab50: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 Reserved:
ab60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
ab70: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0x00F00000 */
ab80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
ab90: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
aba0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
abb0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
abc0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
abd0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
abe0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
abf0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 object returns a
ac00: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
ac10: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 is a vector of t
ac20: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 hese.** bit valu
ac30: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f es expressing I/
ac40: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 O characteristic
ac50: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 s of the mass st
ac60: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 orage.** device
ac70: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 that holds the f
ac80: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 ile that the [sq
ac90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
aca0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a ].** refers to..
acb0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
acc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
acd0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
ace0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
acf0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
ad00: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
ad10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
ad20: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
ad30: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
ad40: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
ad50: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
ad60: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
ad70: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
ad80: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
ad90: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
ada0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
adb0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
adc0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
add0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
ade0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
adf0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
ae00: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
ae10: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
ae20: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
ae30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
ae40: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
ae50: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
ae60: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
ae70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
ae80: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
ae90: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
aea0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
aeb0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
aec0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
aed0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
aee0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 to xWrite(). Th
aef0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
af00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
af10: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e TE property mean
af20: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 s that.** after
af30: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 reboot following
af40: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 a crash or powe
af50: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 r loss, the only
af60: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 bytes in a.** f
af70: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 ile that were wr
af80: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 itten at the app
af90: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d lication level m
afa0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 ight have change
afb0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 d.** and that ad
afc0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 jacent bytes, ev
afd0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 en bytes within
afe0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 the same sector
aff0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 are.** guarantee
b000: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 d to be unchange
b010: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
b020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
b030: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 C
b040: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 0x00000001.#de
b050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
b060: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 P_ATOMIC512
b070: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
b080: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 002.#define SQLI
b090: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
b0a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
b0b0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 0x00000004.#defi
b0c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
b0d0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 ATOMIC2K
b0e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
b0f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
b100: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
b110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
b120: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 00000010.#define
b130: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
b140: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 OMIC8K
b150: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 0x00000020.
b160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
b170: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 OCAP_ATOMIC16K
b180: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
b190: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 000040.#define S
b1a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
b1b0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 IC32K
b1c0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 0x00000080.#d
b1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
b1e0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 AP_ATOMIC64K
b1f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
b200: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
b210: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
b220: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 PPEND
b230: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
b240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
b250: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
b260: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 0x000004
b270: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
b280: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 E_IOCAP_UNDELETA
b290: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 BLE_WHEN_OPEN 0
b2a0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e x00000800.#defin
b2b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
b2c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
b2d0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 TE 0x00001000
b2e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
b2f0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c : File Locking L
b300: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 evels.**.** SQLi
b310: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 te uses one of t
b320: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
b330: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
b340: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
b350: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 calls it makes
b360: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 to the xLock() a
b370: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 nd xUnlock() met
b380: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 hods.** of an [s
b390: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
b3a0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 s] object..*/.#d
b3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
b3c0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 K_NONE
b3d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
b3e0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 _LOCK_SHARED
b3f0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
b400: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
b410: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e ED 2.#defin
b420: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 e SQLITE_LOCK_PE
b430: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 NDING 3.#d
b440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
b450: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 K_EXCLUSIVE
b460: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
b470: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 F: Synchronizati
b480: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a on Type Flags.**
b490: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 .** When SQLite
b4a0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e invokes the xSyn
b4b0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e c() method of an
b4c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
b4d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
b4e0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e it uses a combin
b4f0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 ation of.** thes
b500: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
b510: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
b520: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 rgument..**.** W
b530: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 hen the SQLITE_S
b540: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 YNC_DATAONLY fla
b550: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 g is used, it me
b560: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ans that the.**
b570: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f sync operation o
b580: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 nly needs to flu
b590: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 sh data to mass
b5a0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a storage. Inode.
b5b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e ** information n
b5c0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 eed not be flush
b5d0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 ed. If the lower
b5e0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 four bits of th
b5f0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 e flag.** equal
b600: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
b610: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 AL, that means t
b620: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 o use normal fsy
b630: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a nc() semantics..
b640: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 ** If the lower
b650: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 four bits equal
b660: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
b670: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 , that means.**
b680: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 to use Mac OS X
b690: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 style fullsync i
b6a0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
b6b0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 )..**.** Do not
b6c0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 confuse the SQLI
b6d0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
b6e0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
b6f0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 ULL flags.** wit
b700: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 h the [PRAGMA sy
b710: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 nchronous]=NORMA
b720: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 L and [PRAGMA sy
b730: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a nchronous]=FULL.
b740: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 ** settings. Th
b750: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 e [synchronous p
b760: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 ragma] determine
b770: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 s when calls to
b780: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 the.** xSync VFS
b790: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e method occur an
b7a0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 d applies unifor
b7b0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 mly across all p
b7c0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 latforms..** The
b7d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
b7e0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
b7f0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 YNC_FULL flags d
b800: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 etermine how.**
b810: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 energetic or rig
b820: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 orous or forcefu
b830: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 l the sync opera
b840: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a tions are and.**
b850: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 only make a dif
b860: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f ference on Mac O
b870: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 SX for the defau
b880: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a lt SQLite code..
b890: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 ** (Third-party
b8a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
b8b0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d ons might also m
b8c0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
b8d0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 ion.** between S
b8e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
b8f0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e L and SQLITE_SYN
b900: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e C_FULL, but amon
b910: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 g the.** operati
b920: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 ng systems nativ
b930: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 ely supported by
b940: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 SQLite, only Ma
b950: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 c OSX.** cares a
b960: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 bout the differe
b970: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 nce.).*/.#define
b980: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
b990: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 MAL 0x000
b9a0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 02.#define SQLIT
b9b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 E_SYNC_FULL
b9c0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 0x00003.#de
b9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
b9e0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 _DATAONLY 0
b9f0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 x00010../*.** CA
ba00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
ba10: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 face Open File H
ba20: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b andle.**.** An [
ba30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
ba40: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
ba50: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 an open file in
ba60: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the .** [sqlite3
ba70: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 _vfs | OS interf
ba80: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 ace layer]. Ind
ba90: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 ividual OS inter
baa0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e face.** implemen
bab0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 tations will.**
bac0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 want to subclass
bad0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 this object by
bae0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 appending additi
baf0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 onal fields.** f
bb00: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 or their own use
bb10: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 . The pMethods
bb20: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 entry is a point
bb30: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
bb40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
bb50: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
bb60: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 ines methods for
bb70: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 performing.** I
bb80: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e /O operations on
bb90: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a the open file..
bba0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
bbb0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 t sqlite3_file s
bbc0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 qlite3_file;.str
bbd0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
bbe0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 {. const struc
bbf0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
bc00: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 hods *pMethods;
bc10: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
bc20: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a an open file */.
bc30: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
bc40: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
bc50: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 File Virtual Me
bc60: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a thods Object.**.
bc70: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 ** Every file op
bc80: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c ened by the [sql
bc90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
bca0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 method populates
bcb0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
bcc0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 file] object (or
bcd0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c , more commonly,
bce0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
bcf0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 he.** [sqlite3_f
bd00: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 ile] object) wit
bd10: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 h a pointer to a
bd20: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
bd30: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 is object..** Th
bd40: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
bd50: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 s the methods us
bd60: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ed to perform va
bd70: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 rious operations
bd80: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 .** against the
bd90: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 open file repres
bda0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 ented by the [sq
bdb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
bdc0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ct..**.** If the
bdd0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
bde0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 pen] method sets
bdf0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
be00: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 e.pMethods eleme
be10: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d nt .** to a non-
be20: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
be30: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 en the sqlite3_i
be40: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 o_methods.xClose
be50: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 method.** may b
be60: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 e invoked even i
be70: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
be80: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 fs.xOpen] report
be90: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 ed that it faile
bea0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 d. The.** only
beb0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 way to prevent a
bec0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 call to xClose
bed0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c following a fail
bee0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e ed [sqlite3_vfs.
bef0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 xOpen].** is for
bf00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
bf10: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 s.xOpen] to set
bf20: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
bf30: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e .pMethods elemen
bf40: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a t.** to NULL..**
bf50: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
bf60: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 gument to xSync
bf70: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 may be one of [S
bf80: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
bf90: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 L] or.** [SQLITE
bfa0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 _SYNC_FULL]. Th
bfb0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 e first choice i
bfc0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 s the normal fsy
bfd0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nc()..** The sec
bfe0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 ond choice is a
bff0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
c000: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 ullsync. The [S
c010: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
c020: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 NLY].** flag may
c030: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 be ORed in to i
c040: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c ndicate that onl
c050: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 y the data of th
c060: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f e file.** and no
c070: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 t its inode need
c080: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a s to be synced..
c090: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 **.** The intege
c0a0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 r values to xLoc
c0b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
c0c0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 ) are one of.**
c0d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
c0e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c LITE_LOCK_NONE],
c0f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c100: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
c110: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
c120: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a OCK_RESERVED],.*
c130: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
c140: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
c150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c160: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
c170: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c ..** </ul>.** xL
c180: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 ock() increases
c190: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 the lock. xUnloc
c1a0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 k() decreases th
c1b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 e lock..** The x
c1c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
c1d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b k() method check
c1e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 s whether any da
c1f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c200: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 n,.** either in
c210: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 this process or
c220: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 in some other pr
c230: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e ocess, is holdin
c240: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a g a RESERVED,.**
c250: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 PENDING, or EXC
c260: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 LUSIVE lock on t
c270: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 he file. It ret
c280: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 urns true.** if
c290: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 such a lock exis
c2a0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 ts and false oth
c2b0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erwise..**.** Th
c2c0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 e xFileControl()
c2d0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e method is a gen
c2e0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 eric interface t
c2f0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f hat allows custo
c300: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 m.** VFS impleme
c310: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 ntations to dire
c320: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 ctly control an
c330: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 open file using
c340: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
c350: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
c360: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
c370: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 second "op" argu
c380: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e ment is an.** in
c390: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 teger opcode. T
c3a0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
c3b0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 t is a generic p
c3c0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 ointer intended
c3d0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 to.** point to a
c3e0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
c3f0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 may contain argu
c400: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 ments or space i
c410: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 n which to.** wr
c420: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ite return value
c430: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 s. Potential us
c440: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 es for xFileCont
c450: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a rol() might be.*
c460: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 * functions to e
c470: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c nable blocking l
c480: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 ocks with timeou
c490: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ts, to change th
c4a0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 e.** locking str
c4b0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 ategy (for examp
c4c0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 le to use dot-fi
c4d0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e le locks), to in
c4e0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 quire.** about t
c4f0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c he status of a l
c500: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b ock, or to break
c510: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 stale locks. T
c520: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 he SQLite.** cor
c530: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f e reserves all o
c540: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e pcodes less than
c550: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 100 for its own
c560: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 use..** A [SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
c580: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 TE | list of opc
c590: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 odes] less than
c5a0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 100 is available
c5b0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
c5c0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 s that define a
c5d0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 custom xFileCont
c5e0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c rol method shoul
c5f0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a d use opcodes.**
c600: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 greater than 10
c610: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 0 to avoid confl
c620: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 icts. VFS imple
c630: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
c640: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
c650: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f ITE_NOTFOUND] fo
c660: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f r file control o
c670: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 pcodes that they
c680: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 do not.** recog
c690: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nize..**.** The
c6a0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 xSectorSize() me
c6b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 thod returns the
c6c0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 sector size of
c6d0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 the.** device th
c6e0: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 at underlies the
c6f0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 file. The sect
c700: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a or size is the.*
c710: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 * minimum write
c720: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 that can be perf
c730: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 ormed without di
c740: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 sturbing.** othe
c750: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 r bytes in the f
c760: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 ile. The xDevic
c770: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
c780: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
c790: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f urns a bit vecto
c7a0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 r describing beh
c7b0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a aviors of the.**
c7c0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 underlying devi
c7d0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ce:.**.** <ul>.*
c7e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
c7f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 OCAP_ATOMIC].**
c800: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
c810: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a AP_ATOMIC512].**
c820: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c830: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a CAP_ATOMIC1K].**
c840: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c850: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a CAP_ATOMIC2K].**
c860: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c870: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a CAP_ATOMIC4K].**
c880: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c890: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a CAP_ATOMIC8K].**
c8a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c8b0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a CAP_ATOMIC16K].*
c8c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
c8d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a OCAP_ATOMIC32K].
c8e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c8f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d IOCAP_ATOMIC64K]
c900: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c910: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
c920: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ND].** <li> [SQL
c930: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
c940: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a TIAL].** </ul>.*
c950: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
c960: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
c970: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
c980: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
c990: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
c9a0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
c9b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
c9c0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
c9d0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
c9e0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
c9f0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
ca00: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
ca10: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
ca20: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
ca30: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
ca40: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
ca50: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
ca60: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
ca70: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
ca80: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
ca90: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
caa0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
cab0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
cac0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
cad0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
cae0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
caf0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
cb00: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
cb10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
cb20: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
cb30: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
cb40: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
cb50: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
cb60: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
cb70: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
cb80: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
cb90: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
cba0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
cbb0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
cbc0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
cbd0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
cbe0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
cbf0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
cc00: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
cc10: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
cc20: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
cc30: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
cc40: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
cc50: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
cc60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
cc70: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
cc80: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
cc90: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
cca0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
ccb0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
ccc0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
ccd0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
cce0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
ccf0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
cd00: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
cd10: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
cd20: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
cd30: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
cd40: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
cd50: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
cd60: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
cd70: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
cd80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
cd90: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
cda0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
cdb0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
cdc0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
cdd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
cde0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
cdf0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
ce00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
ce10: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
ce20: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
ce30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
ce40: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
ce50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
ce60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
ce70: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
ce80: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
ce90: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
cea0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
ceb0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
cec0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
ced0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
cee0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
cef0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
cf00: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
cf10: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
cf20: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
cf30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
cf40: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
cf50: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
cf60: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
cf70: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
cf80: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
cf90: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
cfa0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
cfb0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
cfc0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
cfd0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
cfe0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
cff0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
d000: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
d010: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
d020: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
d030: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
d040: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
d050: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
d060: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
d070: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
d080: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
d090: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
d0a0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 2 */. /* Additi
d0b0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
d0c0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
d0d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
d0e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
d0f0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
d100: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
d110: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e s.**.** These in
d120: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
d130: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
d140: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
d150: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
d160: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
d170: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
d180: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
d190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
d1a0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
d1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
d1c0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
d1d0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
d1e0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
d1f0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
d200: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
d210: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
d220: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
d230: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
d240: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
d250: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
d260: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
d270: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
d280: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
d290: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
d2a0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
d2b0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
d2c0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
d2d0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
d2e0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
d2f0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
d300: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
d310: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
d320: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
d330: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
d340: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
d350: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
d360: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e defined..** <ul>
d370: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
d380: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
d390: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
d3a0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
d3b0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 T] opcode is use
d3c0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 d by SQLite to g
d3d0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c ive the VFS.** l
d3e0: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 ayer a hint of h
d3f0: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 ow large the dat
d400: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
d410: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e grow to be durin
d420: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 g the.** current
d430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 transaction. T
d440: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 his hint is not
d450: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
d460: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 accurate but it
d470: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f .** is often clo
d480: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 se. The underly
d490: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 ing VFS might ch
d4a0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 oose to prealloc
d4b0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ate database.**
d4c0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 file space based
d4d0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e on this hint in
d4e0: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 order to help w
d4f0: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 rites to the dat
d500: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 abase.** file ru
d510: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 n faster..**.**
d520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
d530: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a TL_CHUNK_SIZE]].
d540: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
d550: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
d560: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
d570: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 to request that
d580: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e the VFS.** exten
d590: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 ds and truncates
d5a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
d5b0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 le in chunks of
d5c0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 a size specified
d5d0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e .** by the user.
d5e0: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 The fourth argu
d5f0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
d600: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
d610: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e should .** poin
d620: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 t to an integer
d630: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 (type int) conta
d640: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 ining the new ch
d650: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a unk-size to use.
d660: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e ** for the nomin
d670: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 ated database. A
d680: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 llocating databa
d690: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e se file space in
d6a0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 large.** chunks
d6b0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 (say 1MB at a t
d6c0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 ime), may reduce
d6d0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 file-system fra
d6e0: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a gmentation and.*
d6f0: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 * improve perfor
d700: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 mance on some sy
d710: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 stems..**.** <li
d720: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
d730: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a FILE_POINTER]].*
d740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
d750: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
d760: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
d770: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
d780: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
d790: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
d7a0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
d7b0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
d7c0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
d7d0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 nnection. See t
d7e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
d7f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 _control()] docu
d800: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
d810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
d820: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c rmation..**.** <
d830: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d840: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d L_SYNC_OMITTED]]
d850: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
d860: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
d870: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 TTED] opcode is
d880: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
d890: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 ally by.** SQLit
d8a0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c e and sent to al
d8b0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 l VFSes in place
d8c0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 of a call to th
d8d0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a e xSync method.*
d8e0: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 * when the datab
d8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 ase connection h
d900: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 as [PRAGMA synch
d910: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f ronous] set to O
d920: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 FF.)^.** Some sp
d930: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
d940: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c need this signal
d950: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 in order to ope
d960: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a rate correctly.*
d970: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 * when [PRAGMA s
d980: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
d990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
d9a0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 OFF] is set, but
d9b0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 most .** VFSes
d9c0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 do not need this
d9d0: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 signal and shou
d9e0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
d9f0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a re this opcode..
da00: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
da10: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
da20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
da30: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
da40: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 is.** opcode as
da50: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
da60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 rupt the operati
da70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 on of the specia
da80: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 lized VFSes.** t
da90: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 hat do require i
daa0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b t. .**.** <li>[
dab0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
dac0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a N32_AV_RETRY]].*
dad0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
dae0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
daf0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TRY] opcode is u
db00: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
db10: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 automatic.** re
db20: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 try counts and i
db30: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 ntervals for cer
db40: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 tain disk I/O op
db50: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 erations for the
db60: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 .** windows [VFS
db70: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 ] in order to pr
db80: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 ovide robustness
db90: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 in the presence
dba0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 of.** anti-viru
dbb0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 s programs. By
dbc0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e default, the win
dbd0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 dows VFS will re
dbe0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a try file read,.*
dbf0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e * file write, an
dc00: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 d file delete op
dc10: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 erations up to 1
dc20: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 0 times, with a
dc30: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d delay.** of 25 m
dc40: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f illiseconds befo
dc50: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 re the first ret
dc60: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 ry and with the
dc70: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 delay increasing
dc80: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 .** by an additi
dc90: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 onal 25 millisec
dca0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 onds with each s
dcb0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e ubsequent retry.
dcc0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
dcd0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 allows these tw
dce0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 o values (10 ret
dcf0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c ries and 25 mill
dd00: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 iseconds of dela
dd10: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 y).** to be adju
dd20: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 sted. The value
dd30: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f s are changed fo
dd40: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 r all database c
dd50: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 onnections.** wi
dd60: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 thin the same pr
dd70: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 ocess. The argu
dd80: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
dd90: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 r to an array of
dda0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 two.** integers
ddb0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
ddc0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e integer i the n
ddd0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
dde0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
ddf0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
de00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
de10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
de20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
de30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
de40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
de50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
de60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
de70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
de80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
de90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
dea0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
deb0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
dec0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
ded0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
dee0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
def0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
df00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
df10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
df20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
df30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
df40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
df50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
df60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
df70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
df80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
df90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
dfa0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
dfb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
dfc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d g and shared mem
dfd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 ory files used f
dfe0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
dff0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
e000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
e010: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
e020: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
e030: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
e040: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
e050: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
e060: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
e070: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
e080: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
e090: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
e0a0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
e0b0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
e0c0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
e0d0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
e0e0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
e0f0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
e100: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
e110: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
e120: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
e130: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
e140: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
e150: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
e160: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
e170: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
e180: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
e190: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
e1a0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
e1b0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
e1c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
e1d0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
e1e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
e1f0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
e200: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
e210: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
e220: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
e230: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
e240: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
e250: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
e260: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
e270: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
e280: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
e290: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
e2a0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
e2b0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
e2c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
e2d0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
e2e0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
e2f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
e300: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
e310: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
e320: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
e330: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
e340: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
e350: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
e360: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
e370: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
e380: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
e390: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
e3a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
e3b0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
e3c0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
e3d0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
e3e0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
e3f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
e400: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
e410: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
e420: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
e430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
e440: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
e450: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
e460: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
e470: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
e480: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
e490: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
e4a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
e4b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
e4c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
e4d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
e4e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
e4f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
e500: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
e510: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
e520: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
e530: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
e540: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
e550: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
e560: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
e570: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
e580: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
e590: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
e5a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
e5b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
e5c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
e5d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
e5e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
e5f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
e600: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
e610: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
e620: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
e630: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
e640: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
e650: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
e660: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
e670: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
e680: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
e690: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
e6a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
e6b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
e6c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
e6d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
e6e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
e6f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
e700: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
e710: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
e720: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
e730: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
e740: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
e750: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
e760: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
e770: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
e780: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
e790: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
e7a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
e7b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
e7c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
e7d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
e7e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
e7f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
e800: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
e810: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
e820: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
e830: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
e840: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
e850: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
e860: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
e870: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
e880: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
e890: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
e8a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
e8b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
e8c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
e8d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
e8e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
e8f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
e900: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
e910: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
e920: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
e930: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
e940: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
e950: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
e960: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
e970: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
e980: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
e990: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
e9a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
e9b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
e9c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
e9d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
e9e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
e9f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
ea00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
ea10: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
ea20: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
ea30: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
ea40: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
ea50: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
ea60: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
ea70: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
ea80: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
ea90: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
eaa0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
eab0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
eac0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
ead0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
eae0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
eaf0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
eb00: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
eb10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
eb20: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
eb30: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
eb40: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
eb50: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
eb60: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
eb70: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
eb80: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
eb90: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
eba0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
ebb0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
ebc0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
ebd0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
ebe0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
ebf0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
ec00: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
ec10: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
ec20: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
ec30: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
ec40: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
ec50: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
ec60: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
ec70: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
ec80: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
ec90: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
eca0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
ecb0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
ecc0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
ecd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
ece0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
ecf0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
ed00: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
ed10: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
ed20: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
ed30: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
ed40: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
ed50: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 statement. ^If
ed60: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
ed70: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
ed80: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a ontrol returns.*
ed90: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 * any result cod
eda0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
edb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c LITE_OK] or [SQL
edc0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 ITE_NOTFOUND], t
edd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 hat means.** tha
ede0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e t the VFS encoun
edf0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 tered an error w
ee00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 hile handling th
ee10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 e [PRAGMA] and t
ee20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f he.** compilatio
ee30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 n of the PRAGMA
ee40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 fails with an er
ee50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ror. ^The [SQLI
ee60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
ee70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
ee80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 occurs at the b
ee90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 eginning of prag
eea0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 ma statement ana
eeb0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 lysis and so.**
eec0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 it is able to ov
eed0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 erride built-in
eee0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
eef0: 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f nts..** </ul>.*/
ef00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ef10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
ef20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
ef30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
ef40: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
ef50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
ef60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
ef70: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
ef80: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
ef90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
efa0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
efb0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
efc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
efd0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
efe0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
eff0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
f000: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
f010: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
f020: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
f030: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
f040: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
f050: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
f060: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
f070: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
f080: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
f090: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
f0a0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
f0b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
f0c0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
f0d0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
f0e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
f0f0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
f100: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
f110: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
f120: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
f130: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
f140: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
f150: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
f160: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 13.#define SQLI
f170: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 TE_FCNTL_PRAGMA
f180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
f190: 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 14../*.** CAPI3R
f1a0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 EF: Mutex Handle
f1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 .**.** The mutex
f1c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 module within S
f1d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 QLite defines [s
f1e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f qlite3_mutex] to
f1f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 be an.** abstra
f200: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 ct type for a mu
f210: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 tex object. The
f220: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 SQLite core nev
f230: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 er looks.** at t
f240: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
f250: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e esentation of an
f260: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
f270: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 . It only.** de
f280: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 als with pointer
f290: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
f2a0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 3_mutex] object.
f2b0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 .**.** Mutexes a
f2c0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
f2d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
f2e0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 alloc()]..*/.typ
f2f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
f300: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 te3_mutex sqlite
f310: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 3_mutex;../*.**
f320: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
f330: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a erface Object.**
f340: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
f350: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 of the sqlite3_v
f360: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 fs object define
f370: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
f380: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 between.** the S
f390: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 QLite core and t
f3a0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 he underlying op
f3b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
f3c0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e The "vfs".** in
f3d0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
f3e0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 object stands f
f3f0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 or "virtual file
f400: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a system". See.*
f410: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 * the [VFS | VFS
f420: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
f430: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f for further info
f440: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 rmation..**.** T
f450: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
f460: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 iVersion field i
f470: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 s initially 1 bu
f480: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 t may be larger
f490: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 in.** future ver
f4a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
f4b0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 Additional fie
f4c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e lds may be appen
f4d0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f ded to this.** o
f4e0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 bject when the i
f4f0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 Version value is
f500: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 increased. Not
f510: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 e that the struc
f520: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 ture.** of the s
f530: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
f540: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 t changes in the
f550: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 transaction bet
f560: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 ween.** SQLite v
f570: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 ersion 3.5.9 and
f580: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 3.6.0 and yet t
f590: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
f5a0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 d was not.** mod
f5b0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ified..**.** The
f5c0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 szOsFile field
f5d0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
f5e0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 he subclassed [s
f5f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 qlite3_file].**
f600: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 structure used b
f610: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 y this VFS. mxP
f620: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d athname is the m
f630: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
f640: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 .** a pathname i
f650: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a n this VFS..**.*
f660: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c * Registered sql
f670: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 ite3_vfs objects
f680: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c are kept on a l
f690: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 inked list forme
f6a0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 d by.** the pNex
f6b0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 t pointer. The
f6c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
f6d0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 ister()].** and
f6e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 [sqlite3_vfs_unr
f6f0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 egister()] inter
f700: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 faces manage thi
f710: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 s list.** in a t
f720: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 hread-safe way.
f730: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
f740: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 s_find()] interf
f750: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 ace.** searches
f760: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 the list. Neith
f770: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
f780: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 on code nor the
f790: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 VFS.** implement
f7a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ation should use
f7b0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
f7c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e er..**.** The pN
f7d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 ext field is the
f7e0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 only field in t
f7f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
f800: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
f810: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
f820: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
f830: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
f840: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
f850: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 this field while
f860: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 holding a parti
f870: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 cular static mut
f880: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ex..** The appli
f890: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
f8a0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 ver modify anyth
f8b0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 ing within the s
f8c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
f8d0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
f8e0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
f8f0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 gistered..**.**
f900: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 The zName field
f910: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f holds the name o
f920: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 f the VFS module
f930: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 . The name must
f940: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 .** be unique ac
f950: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 ross all VFS mod
f960: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 ules..**.** [[sq
f970: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
f980: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 ].** ^SQLite gua
f990: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
f9a0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
f9b0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a eter to xOpen.**
f9c0: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c is either a NUL
f9d0: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 L pointer or str
f9e0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 ing obtained.**
f9f0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 from xFullPathna
fa00: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 me() with an opt
fa10: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 ional suffix add
fa20: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 ed..** ^If a suf
fa30: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 fix is added to
fa40: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
fa50: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c rameter, it will
fa60: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 .** consist of a
fa70: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 single "-" char
fa80: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 acter followed b
fa90: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a y no more than.*
faa0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 * 11 alphanumeri
fab0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 c and/or "-" cha
fac0: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c racters..** ^SQL
fad0: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 ite further guar
fae0: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 antees that.** t
faf0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
fb00: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 e valid and unch
fb10: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f anged until xClo
fb20: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 se() is.** calle
fb30: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 d. Because of th
fb40: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 e previous sente
fb50: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c nce,.** the [sql
fb60: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 ite3_file] can s
fb70: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f afely store a po
fb80: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 inter to the.**
fb90: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e filename if it n
fba0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 eeds to remember
fbb0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f the filename fo
fbc0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a r some reason..*
fbd0: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 * If the zFilena
fbe0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 me parameter to
fbf0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 xOpen is a NULL
fc00: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 pointer then xOp
fc10: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e en.** must inven
fc20: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 t its own tempor
fc30: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 ary name for the
fc40: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 file. ^Wheneve
fc50: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e r the .** xFilen
fc60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
fc70: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c NULL it will al
fc80: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 so be the case t
fc90: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 hat the.** flags
fca0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 parameter will
fcb0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
fcc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
fcd0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 SE]..**.** The f
fce0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
fcf0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 xOpen() include
fd00: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 s all bits set i
fd10: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 n.** the flags a
fd20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
fd30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
fd40: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f Or if [sqlite3_
fd50: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 open()].** or [s
fd60: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
fd70: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 is used, then f
fd80: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 lags includes at
fd90: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 least.** [SQLIT
fda0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
fdb0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ] | [SQLITE_OPEN
fdc0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 _CREATE]. .** If
fdd0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 xOpen() opens a
fde0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 file read-only
fdf0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f then it sets *pO
fe00: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e utFlags to.** in
fe10: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
fe20: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f EN_READONLY]. O
fe30: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f ther bits in *pO
fe40: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 utFlags may be s
fe50: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 et..**.** ^(SQLi
fe60: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 te will also add
fe70: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
fe80: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
fe90: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 he xOpen().** ca
fea0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ll, depending on
feb0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e the object bein
fec0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 g opened:.**.**
fed0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 <ul>.** <li> [S
fee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
fef0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
ff00: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
ff10: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
ff20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
ff30: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 MP_DB].** <li>
ff40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
ff50: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c P_JOURNAL].** <l
ff60: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
ff70: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a _TRANSIENT_DB].*
ff80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
ff90: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d OPEN_SUBJOURNAL]
ffa0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
ffb0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
ffc0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
ffd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c [SQLITE_OPEN_WAL
ffe0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a ].** </ul>)^.**.
fff0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 ** The file I/O
10000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 implementation c
10010 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 an use the objec
10020 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a t type flags to.
10030 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 ** change the wa
10040 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 y it deals with
10050 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d files. For exam
10060 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
10070 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 ion.** that does
10080 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 not care about
10090 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f crash recovery o
100a0 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 r rollback might
100b0 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 make.** the ope
100c0 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 n of a journal f
100d0 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 ile a no-op. Wr
100e0 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 ites to this jou
100f0 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c rnal would.** al
10100 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e so be no-ops, an
10110 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f d any attempt to
10120 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 read the journa
10130 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a l would return.*
10140 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 * SQLITE_IOERR.
10150 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e Or the implemen
10160 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 tation might rec
10170 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 ognize that a da
10180 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 tabase.** file w
10190 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 ill be doing pag
101a0 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 e-aligned sector
101b0 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 reads and write
101c0 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a s in a random.**
101d0 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 order and set u
101e0 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 p its I/O subsys
101f0 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e tem accordingly.
10200 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 .**.** SQLite mi
10210 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ght also add one
10220 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
10230 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
10240 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a Open method:.**.
10250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
10260 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
10270 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c ETEONCLOSE].** <
10280 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
10290 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c _EXCLUSIVE].** <
102a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b /ul>.**.** The [
102b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
102c0 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 TEONCLOSE] flag
102d0 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 means the file s
102e0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 hould be.** dele
102f0 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 ted when it is c
10300 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 losed. ^The [SQ
10310 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
10320 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c ONCLOSE].** will
10330 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 be set for TEMP
10340 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 databases and t
10350 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 heir journals, t
10360 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 ransient.** data
10370 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f bases, and subjo
10380 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 urnals..**.** ^T
10390 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
103a0 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 EXCLUSIVE] flag
103b0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 is always used i
103c0 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a n conjunction.**
103d0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
103e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 E_OPEN_CREATE] f
103f0 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 lag, which are b
10400 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 oth directly.**
10410 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 analogous to the
10420 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 O_EXCL and O_CR
10430 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 EAT flags of the
10440 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a POSIX open().**
10450 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 API. The SQLIT
10460 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
10470 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 flag, when pair
10480 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
10490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
104a0 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 TE, is used to i
104b0 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c ndicate that fil
104c0 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a e should always.
104d0 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 ** be created, a
104e0 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e nd that it is an
104f0 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 error if it alr
10500 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 eady exists..**
10510 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e It is <i>not</i>
10520 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 used to indicat
10530 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c e the file shoul
10540 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 d be opened .**
10550 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 for exclusive ac
10560 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 cess..**.** ^At
10570 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 least szOsFile b
10580 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 ytes of memory a
10590 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
105a0 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c SQLite.** to hol
105b0 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f d the [sqlite3_
105c0 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 file] structure
105d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 passed as the th
105e0 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ird.** argument
105f0 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 to xOpen. The x
10600 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 Open method does
10610 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 not have to.**
10620 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 allocate the str
10630 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c ucture; it shoul
10640 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 d just fill it i
10650 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a n. Note that.**
10660 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
10670 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 d must set the s
10680 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
10690 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a hods to either.*
106a0 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 * a valid [sqlit
106b0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
106c0 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c bject or to NULL
106d0 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f . xOpen must do
106e0 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 .** this even if
106f0 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e the open fails.
10700 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 SQLite expects
10710 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 that the sqlite
10720 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 3_file.pMethods.
10730 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 ** element will
10740 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 be valid after x
10750 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 Open returns reg
10760 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 ardless of the s
10770 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 uccess.** or fai
10780 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 lure of the xOpe
10790 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b n call..**.** [[
107a0 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 sqlite3_vfs.xAcc
107b0 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c ess]].** ^The fl
107c0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
107d0 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 xAccess() may be
107e0 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
107f0 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 EXISTS].** to te
10800 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 st for the exist
10810 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 ence of a file,
10820 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
10830 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a S_READWRITE] to.
10840 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 ** test whether
10850 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 a file is readab
10860 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c le and writable,
10870 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 or [SQLITE_ACCE
10880 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 SS_READ].** to t
10890 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
108a0 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 le is at least r
108b0 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 eadable. The f
108c0 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 ile can be a.**
108d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
108e0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c ^SQLite will al
108f0 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 ways allocate at
10900 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d least mxPathnam
10910 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 e+1 bytes for th
10920 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 e.** output buff
10930 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 er xFullPathname
10940 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a . The exact siz
10950 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 e of the output
10960 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 buffer.** is als
10970 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 o passed as a pa
10980 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 rameter to both
10990 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 methods. If the
109a0 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a output buffer.*
109b0 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 * is not large e
109c0 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 nough, [SQLITE_C
109d0 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 ANTOPEN] should
109e0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e be returned. Sin
109f0 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 ce this is.** ha
10a00 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c ndled as a fatal
10a10 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 error by SQLite
10a20 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 , vfs implementa
10a30 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 tions should end
10a40 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 eavor.** to prev
10a50 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 ent this by sett
10a60 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 ing mxPathname t
10a70 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 o a sufficiently
10a80 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a large value..**
10a90 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
10aa0 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c ess(), xSleep(),
10ab0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c xCurrentTime(),
10ac0 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d and xCurrentTim
10ad0 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 eInt64().** inte
10ae0 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 rfaces are not s
10af0 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
10b00 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
10b10 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
10b20 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
10b30 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
10b40 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
10b50 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
10b60 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
10b70 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
10b80 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
10b90 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
10ba0 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
10bb0 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
10bc0 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
10bd0 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
10be0 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
10bf0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
10c00 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 ed..** The xSlee
10c10 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 p() method cause
10c20 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 s the calling th
10c30 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f read to sleep fo
10c40 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 r at.** least th
10c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 e number of micr
10c60 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 oseconds given.
10c70 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
10c80 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
10c90 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
10ca0 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
10cb0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
10cc0 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 and time as.** a
10cd0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
10ce0 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 value..** ^The x
10cf0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
10d00 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e () method return
10d10 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 s, as an integer
10d20 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 , the Julian.**
10d30 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 Day Number multi
10d40 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 plied by 8640000
10d50 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0 (the number of
10d60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e milliseconds in
10d70 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 .** a 24-hour d
10d80 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 ay). .** ^SQLit
10d90 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 e will use the x
10da0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
10db0 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 () method to get
10dc0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
10dd0 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 date and time if
10de0 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 that method is
10df0 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 available (if iV
10e00 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a ersion is 2 or .
10e10 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 ** greater and t
10e20 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e he function poin
10e30 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 ter is not NULL)
10e40 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 and will fall b
10e50 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 ack.** to xCurre
10e60 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 ntTime() if xCur
10e70 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10e80 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
10e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 **.** ^The xSetS
10ea0 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 ystemCall(), xGe
10eb0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 tSystemCall(), a
10ec0 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 nd xNestSystemCa
10ed0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a ll() interfaces.
10ee0 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 ** are not used
10ef0 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f by the SQLite co
10f00 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f re. These optio
10f10 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 nal interfaces a
10f20 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 re provided.** b
10f30 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 y some VFSes to
10f40 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 facilitate testi
10f50 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f ng of the VFS co
10f60 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e de. By overridin
10f70 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c g .** system cal
10f80 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e ls with function
10f90 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 s under its cont
10fa0 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 rol, a test prog
10fb0 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c ram can.** simul
10fc0 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 ate faults and e
10fd0 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 rror conditions
10fe0 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 that would other
10ff0 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c wise be difficul
11000 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 t.** or impossib
11010 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 le to induce. T
11020 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d he set of system
11030 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 calls that can
11040 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a be overridden.**
11050 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 varies from one
11060 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c VFS to another,
11070 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 and from one ve
11080 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d rsion of the sam
11090 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 e VFS to the.**
110a0 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
110b0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 ons that use the
110c0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 se interfaces mu
110d0 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 st be prepared f
110e0 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c or any.** or all
110f0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 of these interf
11100 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 aces to be NULL
11110 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 or for their beh
11120 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a avior to change.
11130 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 ** from one rele
11140 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ase to the next.
11150 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d Applications m
11160 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 ust not attempt
11170 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 to access.** any
11180 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 of these method
11190 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f s if the iVersio
111a0 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 n of the VFS is
111b0 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a less than 3..*/.
111c0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
111d0 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 qlite3_vfs sqlit
111e0 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 e3_vfs;.typedef
111f0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 void (*sqlite3_s
11200 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 yscall_ptr)(void
11210 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 );.struct sqlite
11220 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 3_vfs {. int iV
11230 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 ersion;
11240 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 /* Structure
11250 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 version number (
11260 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a currently 3) */.
11270 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 int szOsFile;
11280 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 /* Si
11290 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 ze of subclassed
112a0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f sqlite3_file */
112b0 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d . int mxPathnam
112c0 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d e; /* M
112d0 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 aximum file path
112e0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 name length */.
112f0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e sqlite3_vfs *pN
11300 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 ext; /* Nex
11310 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 t registered VFS
11320 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
11330 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f *zName; /
11340 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 * Name of this v
11350 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
11360 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 em */. void *pA
11370 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
11380 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 /* Pointer to a
11390 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 pplication-speci
113a0 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e fic data */. in
113b0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
113c0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
113d0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
113e0 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 te3_file*,.
113f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c int fl
11400 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c ags, int *pOutFl
11410 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 ags);. int (*xD
11420 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 elete)(sqlite3_v
11430 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
11440 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 *zName, int sync
11450 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 Dir);. int (*xA
11460 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 ccess)(sqlite3_v
11470 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
11480 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 *zName, int flag
11490 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 s, int *pResOut)
114a0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 ;. int (*xFullP
114b0 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 athname)(sqlite3
114c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
114d0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f r *zName, int nO
114e0 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b ut, char *zOut);
114f0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 . void *(*xDlOp
11500 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
11510 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 , const char *zF
11520 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 ilename);. void
11530 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c (*xDlError)(sql
11540 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
11550 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 Byte, char *zErr
11560 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 Msg);. void (*(
11570 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 *xDlSym)(sqlite3
11580 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e _vfs*,void*, con
11590 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c st char *zSymbol
115a0 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 ))(void);. void
115b0 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c (*xDlClose)(sql
115c0 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a ite3_vfs*, void*
115d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 );. int (*xRand
115e0 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f omness)(sqlite3_
115f0 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c vfs*, int nByte,
11600 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
11610 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 int (*xSleep)(sq
11620 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
11630 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 microseconds);.
11640 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 int (*xCurrentT
11650 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ime)(sqlite3_vfs
11660 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 *, double*);. i
11670 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 nt (*xGetLastErr
11680 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a or)(sqlite3_vfs*
11690 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a , int, char *);.
116a0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
116b0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
116c0 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 in version 1 of
116d0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
116e0 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e bject. ** defin
116f0 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 ition. Those th
11700 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 at follow are ad
11710 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 ded in version 2
11720 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 or later. */.
11730 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 int (*xCurrentT
11740 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 imeInt64)(sqlite
11750 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 3_vfs*, sqlite3_
11760 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 int64*);. /*.
11770 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
11780 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
11790 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 ions 1 and 2 of
117a0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
117b0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 bject.. ** Thos
117c0 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 e below are for
117d0 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 version 3 and gr
117e0 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e eater.. */. in
117f0 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 t (*xSetSystemCa
11800 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
11810 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
11820 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 ame, sqlite3_sys
11830 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c call_ptr);. sql
11840 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 ite3_syscall_ptr
11850 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c (*xGetSystemCal
11860 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
11870 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
11880 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 me);. const cha
11890 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d r *(*xNextSystem
118a0 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
118b0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
118c0 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a zName);. /*. *
118d0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
118e0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
118f0 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 ons 1 through 3
11900 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
11910 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e s object.. ** N
11920 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 ew fields may be
11930 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 appended in fig
11940 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 ure versions. T
11950 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a he iVersion. **
11960 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 value will incr
11970 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 ement whenever t
11980 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 his happens. .
11990 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
119a0 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 I3REF: Flags for
119b0 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 the xAccess VFS
119c0 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 method.**.** Th
119d0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
119e0 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 tants can be use
119f0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 d as the third p
11a00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
11a10 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
11a20 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 d of an [sqlite3
11a30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 _vfs] object. T
11a40 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a hey determine.**
11a50 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 what kind of pe
11a60 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 rmissions the xA
11a70 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 ccess method is
11a80 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 looking for..**
11a90 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
11aa0 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 SS_EXISTS, the x
11ab0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
11ac0 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 simply checks w
11ad0 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
11ae0 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 exists..** With
11af0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
11b00 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 ADWRITE, the xAc
11b10 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 cess method.** c
11b20 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
11b30 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 e named director
11b40 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 y is both readab
11b50 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a le and writable.
11b60 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 ** (in other wor
11b70 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e ds, if files can
11b80 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 be added, remov
11b90 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 ed, and renamed
11ba0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 within.** the di
11bb0 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 rectory)..** The
11bc0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
11bd0 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e EADWRITE constan
11be0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 t is currently u
11bf0 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a sed only by the.
11c00 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 ** [temp_store_d
11c10 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
11c20 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f , though this co
11c30 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 uld change in a
11c40 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 future.** releas
11c50 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 e of SQLite..**
11c60 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
11c70 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 SS_READ, the xAc
11c80 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 cess method.** c
11c90 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
11ca0 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 e file is readab
11cb0 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f le. The SQLITE_
11cc0 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 ACCESS_READ cons
11cd0 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 tant is.** curre
11ce0 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f ntly unused, tho
11cf0 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 ugh it might be
11d00 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 used in a future
11d10 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 release of.** S
11d20 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
11d30 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
11d40 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 EXISTS 0.#def
11d50 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
11d60 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 S_READWRITE 1
11d70 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d /* Used by PRAGM
11d80 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 A temp_store_dir
11d90 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e ectory */.#defin
11da0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
11db0 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a READ 2 /*
11dc0 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a Unused */../*.*
11dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
11de0 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f s for the xShmLo
11df0 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a ck VFS method.**
11e00 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 .** These intege
11e10 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 r constants defi
11e20 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c ne the various l
11e30 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e ocking operation
11e40 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 s.** allowed by
11e50 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 the xShmLock met
11e60 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f hod of [sqlite3_
11e70 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 io_methods]. Th
11e80 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 e.** following a
11e90 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 re the only lega
11ea0 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f l combinations o
11eb0 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a f flags to the.*
11ec0 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f * xShmLock metho
11ed0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
11ee0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
11ef0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
11f00 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c SHM_SHARED.** <l
11f10 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
11f20 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
11f30 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c _EXCLUSIVE.** <l
11f40 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 i> SQLITE_SHM_U
11f50 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 NLOCK | SQLITE_S
11f60 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 HM_SHARED.** <li
11f70 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e > SQLITE_SHM_UN
11f80 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
11f90 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c M_EXCLUSIVE.** <
11fa0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 /ul>.**.** When
11fb0 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 unlocking, the s
11fc0 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 ame SHARED or EX
11fd0 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 CLUSIVE flag mus
11fe0 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 t be supplied as
11ff0 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f .** was given no
12000 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
12010 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a ng lock. .**.**
12020 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 The xShmLock me
12030 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 thod can transit
12040 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f ion between unlo
12050 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 cked and SHARED
12060 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e or.** between un
12070 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 locked and EXCLU
12080 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 SIVE. It cannot
12090 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 transition betw
120a0 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e een SHARED.** an
120b0 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a d EXCLUSIVE..*/.
120c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
120d0 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 HM_UNLOCK
120e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
120f0 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 _SHM_LOCK
12100 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
12110 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 TE_SHM_SHARED
12120 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
12130 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
12140 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 VE 8../*.** C
12150 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d API3REF: Maximum
12160 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a xShmLock index.
12170 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
12180 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 ck method on [sq
12190 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
121a0 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 ] may use values
121b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e .** between 0 an
121c0 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 d this upper bou
121d0 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 nd as its "offse
121e0 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 t" argument..**
121f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
12200 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d will never attem
12210 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 pt to acquire or
12220 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f release a.** lo
12230 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 ck outside of th
12240 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 is range.*/.#def
12250 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e ine SQLITE_SHM_N
12260 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a LOCK 8...
12270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
12280 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 Initialize The S
12290 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
122a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
122b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
122c0 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 utine initialize
122d0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 s the.** SQLite
122e0 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 library. ^The s
122f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
12300 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 ) routine.** dea
12310 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 llocates any res
12320 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 ources that were
12330 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 allocated by sq
12340 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12350 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ()..** These rou
12360 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e tines are design
12370 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f ed to aid in pro
12380 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
12390 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 ion and.** shutd
123a0 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 own on embedded
123b0 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 systems. Workst
123c0 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f ation applicatio
123d0 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 ns using.** SQLi
123e0 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e te normally do n
123f0 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b ot need to invok
12400 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 e either of thes
12410 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
12420 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
12430 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
12440 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
12450 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
12460 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 .** the first ti
12470 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
12480 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
12490 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 ed during the li
124a0 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 fetime of.** the
124b0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 process, or if
124c0 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 it is the first
124d0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
124e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
124f0 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e oked.** followin
12500 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 g a call to sqli
12510 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 te3_shutdown().
12520 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 ^(Only an effec
12530 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 tive call.** of
12540 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12550 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e ze() does any in
12560 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 itialization. A
12570 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a ll other calls.*
12580 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e * are harmless n
12590 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 o-ops.)^.**.** A
125a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
125b0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 _shutdown() is a
125c0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 n "effective" ca
125d0 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 ll if it is the
125e0 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f first.** call to
125f0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
12600 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 n() since the la
12610 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 st sqlite3_initi
12620 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 alize(). ^(Only
12630 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 .** an effective
12640 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
12650 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 _shutdown() does
12660 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a any deinitializ
12670 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 ation..** All ot
12680 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 her valid calls
12690 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
126a0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 own() are harmle
126b0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
126c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
126d0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 nitialize() inte
126e0 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 rface is threads
126f0 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 afe, but sqlite3
12700 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 _shutdown().** i
12710 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 s not. The sqli
12720 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
12730 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e nterface must on
12740 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f ly be called fro
12750 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 m a.** single th
12760 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 read. All open
12770 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12780 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 tions] must be c
12790 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a losed and all.**
127a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 other SQLite re
127b0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 sources must be
127c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f deallocated prio
127d0 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a r to invoking.**
127e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
127f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 n()..**.** Among
12800 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e other things, ^
12810 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12820 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 ze() will invoke
12830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 .** sqlite3_os_i
12840 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c nit(). Similarl
12850 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 y, ^sqlite3_shut
12860 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 down().** will i
12870 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 nvoke sqlite3_os
12880 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 _end()..**.** ^T
12890 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
128a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
128b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
128c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a OK] on success..
128d0 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 ** ^If for some
128e0 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f reason, sqlite3_
128f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
12900 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 unable to initia
12910 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 lize.** the libr
12920 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 ary (perhaps it
12930 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
12940 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 ocate a needed r
12950 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 esource such.**
12960 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 as a mutex) it r
12970 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 eturns an [error
12980 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 code] other tha
12990 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a n [SQLITE_OK]..*
129a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
129b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
129c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
129d0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d internally by m
129e0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c any other.** SQL
129f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 ite interfaces s
12a00 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 o that an applic
12a10 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f ation usually do
12a20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a es not need to.*
12a30 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
12a40 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
12a50 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 rectly. For exa
12a60 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f mple, [sqlite3_o
12a70 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 pen()].** calls
12a80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12a90 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 ze() so the SQLi
12aa0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
12ab0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
12ac0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 .** initialized
12ad0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 when [sqlite3_op
12ae0 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 en()] is called
12af0 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 if it has not be
12b00 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 initialized.**
12b10 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 already. ^Howev
12b20 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 er, if SQLite is
12b30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
12b40 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
12b50 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d AUTOINIT].** com
12b60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
12b70 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d , then the autom
12b80 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 atic calls to sq
12b90 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12ba0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 ().** are omitte
12bb0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 d and the applic
12bc0 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 ation must call
12bd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12be0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a ze() directly.**
12bf0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
12c00 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
12c10 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 interface. For
12c20 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 maximum portabi
12c30 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 lity,.** it is r
12c40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
12c50 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 applications alw
12c60 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ays invoke sqlit
12c70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
12c80 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f ** directly prio
12c90 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
12ca0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
12cb0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 rface. Future r
12cc0 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 eleases.** of SQ
12cd0 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 Lite may require
12ce0 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 this. In other
12cf0 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 words, the beha
12d00 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a vior exhibited.*
12d10 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 * when SQLite is
12d20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b compiled with [
12d30 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
12d40 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f INIT] might beco
12d50 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c me the.** defaul
12d60 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f t behavior in so
12d70 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
12d80 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a e of SQLite..**.
12d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
12da0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 s_init() routine
12db0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d does operating-
12dc0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a system specific.
12dd0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ** initializatio
12de0 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
12df0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 library. The sq
12e00 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
12e10 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 * routine undoes
12e20 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 the effect of s
12e30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
12e40 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 . Typical tasks
12e50 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 .** performed by
12e60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
12e70 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 include allocati
12e80 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 on or deallocati
12e90 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 on.** of static
12ea0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 resources, initi
12eb0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f alization of glo
12ec0 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a bal variables,.*
12ed0 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 * setting up a d
12ee0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
12ef0 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 vfs] module, or
12f00 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 setting up.** a
12f10 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
12f20 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c ation using [sql
12f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
12f40 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
12f50 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
12f60 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 er invoke either
12f70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12f80 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
12f90 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 _os_end() direct
12fa0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 ly. The applica
12fb0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 tion should only
12fc0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
12fd0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12fe0 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 and sqlite3_shut
12ff0 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c down(). The sql
13000 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
13010 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 * interface is c
13020 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 alled automatica
13030 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 lly by sqlite3_i
13040 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a nitialize() and.
13050 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ** sqlite3_os_en
13060 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 d() is called by
13070 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
13080 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 n(). Appropriat
13090 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
130a0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 ions for sqlite3
130b0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
130c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
130d0 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 ** are built int
130e0 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 o SQLite when it
130f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
13100 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 Unix, Windows,
13110 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e or OS/2..** When
13120 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 [custom builds
13130 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 | built for othe
13140 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 r platforms].**
13150 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 (using the [SQLI
13160 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 TE_OS_OTHER=1] c
13170 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
13180 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 ption) the appli
13190 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 cation must supp
131a0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d ly a suitable im
131b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 plementation for
131c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 .** sqlite3_os_i
131d0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 nit() and sqlite
131e0 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 3_os_end(). An
131f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 application-supp
13200 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e lied.** implemen
13210 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
13220 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 3_os_init() or s
13230 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a qlite3_os_end().
13240 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b ** must return [
13250 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
13260 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f ccess and some o
13270 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 ther [error code
13280 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 ] upon.** failur
13290 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
132a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 int sqlite3_ini
132b0 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 tialize(void);.S
132c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
132d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 lite3_shutdown(v
132e0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
132f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f int sqlite3_os_
13300 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 init(void);.SQLI
13310 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
13320 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
13330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
13340 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
13350 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
13360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
13370 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
13380 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
13390 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e make global con
133a0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
133b0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 anges to SQLite
133c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 in order to tune
133d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 SQLite to the s
133e0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
133f0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
13400 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c ion. The defaul
13410 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
13420 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
13430 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 or most.** appli
13440 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 cations and so t
13450 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
13460 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 sually not neces
13470 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 sary. It is.**
13480 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 provided to supp
13490 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 ort rare applica
134a0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 tions with unusu
134b0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 al needs..**.**
134c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
134d0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
134e0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
134f0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
13500 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 on.** must insur
13510 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 e that no other
13520 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
13530 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 s are invoked by
13540 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 other.** thread
13550 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f s while sqlite3_
13560 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e config() is runn
13570 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 ing. Furthermor
13580 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e, sqlite3_confi
13590 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 g().** may only
135a0 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 be invoked prior
135b0 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 to library init
135c0 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 ialization using
135d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 .** [sqlite3_ini
135e0 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 tialize()] or af
135f0 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 ter shutdown by
13600 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
13610 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c n()]..** ^If sql
13620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
13630 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
13640 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
13650 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a e()] and before.
13660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
13670 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 down()] then it
13680 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 will return SQLI
13690 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f TE_MISUSE..** No
136a0 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 te, however, tha
136b0 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t ^sqlite3_confi
136c0 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 g() can be calle
136d0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
136e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
136f0 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 on of an applica
13700 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 tion-defined [sq
13710 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d lite3_os_init()]
13720 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
13730 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 t argument to sq
13740 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
13750 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 s an integer.**
13760 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f [configuration o
13770 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
13780 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
13790 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
137a0 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
137b0 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
137c0 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
137d0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
137e0 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 n the [configura
137f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 tion option].**
13800 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
13810 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 ument..**.** ^Wh
13820 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 en a configurati
13830 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 on option is set
13840 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
13850 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 () returns [SQLI
13860 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 TE_OK]..** ^If t
13870 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b he option is unk
13880 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 nown or SQLite i
13890 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 s unable to set
138a0 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 the option.** th
138b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
138c0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
138d0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e ro [error code].
138e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
138f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 nt sqlite3_confi
13900 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a g(int, ...);../*
13910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
13920 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 nfigure database
13930 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a connections.**.
13940 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 ** The sqlite3_d
13950 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 b_config() inter
13960 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
13970 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 make configurati
13980 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
13990 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
139a0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 nection]. The i
139b0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 nterface is simi
139c0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lar to.** [sqlit
139d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 e3_config()] exc
139e0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 ept that the cha
139f0 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 nges apply to a
13a00 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 single.** [datab
13a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13a20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 (specified in th
13a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
13a40 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 )..**.** The sec
13a50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
13a60 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
13a70 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 g(D,V,...) is t
13a80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 he.** [SQLITE_DB
13a90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
13aa0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e | configuration
13ab0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 verb] - an inte
13ac0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 ger code .** tha
13ad0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 t indicates what
13ae0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b aspect of the [
13af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13b00 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f ion] is being co
13b10 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 nfigured..** Sub
13b20 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
13b30 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 s vary depending
13b40 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 on the configur
13b50 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a ation verb..**.*
13b60 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
13b70 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 te3_db_config()
13b80 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
13b90 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
13ba0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 ** the call is c
13bb0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 onsidered succes
13bc0 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f sful..*/.SQLITE_
13bd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
13be0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 db_config(sqlite
13bf0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3*, int op, ...)
13c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
13c10 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
13c20 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a tion Routines.**
13c30 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
13c40 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 of this object d
13c50 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
13c60 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c face between SQL
13c70 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c ite.** and low-l
13c80 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
13c90 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
13ca0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 .**.** This obje
13cb0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e ct is used in on
13cc0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 ly one place in
13cd0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 the SQLite inter
13ce0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 face..** A point
13cf0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
13d00 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
13d10 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 is the argument
13d20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
13d30 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 config()] when t
13d40 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
13d50 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 option is.** [S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
13d70 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f LOC] or [SQLITE_
13d80 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
13d90 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 ]. .** By creat
13da0 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 ing an instance
13db0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a of this object.*
13dc0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 * and passing it
13dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
13de0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e fig]([SQLITE_CON
13df0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 FIG_MALLOC]).**
13e00 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 during configura
13e10 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 tion, an applica
13e20 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 tion can specify
13e30 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
13e40 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
13e50 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 tion subsystem f
13e60 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 or SQLite to use
13e70 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a for all of its.
13e80 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ** dynamic memor
13e90 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e y needs..**.** N
13ea0 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 ote that SQLite
13eb0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 comes with sever
13ec0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d al [built-in mem
13ed0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a ory allocators].
13ee0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 ** that are perf
13ef0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 ectly adequate f
13f00 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d or the overwhelm
13f10 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 ing majority of
13f20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
13f30 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 and that this ob
13f40 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 ject is only use
13f50 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 ful to a tiny mi
13f60 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 nority of applic
13f70 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 ations.** with s
13f80 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 pecialized memor
13f90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
13fa0 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 uirements. This
13fb0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c object is.** al
13fc0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 so used during t
13fd0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 esting of SQLite
13fe0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 in order to spe
13ff0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 cify an alternat
14000 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ive.** memory al
14010 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d locator that sim
14020 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 ulates memory ou
14030 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 t-of-memory cond
14040 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 itions in.** ord
14050 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 er to verify tha
14060 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 t SQLite recover
14070 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f s gracefully fro
14080 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 m such.** condit
14090 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ions..**.** The
140a0 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f xMalloc, xReallo
140b0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 c, and xFree met
140c0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c hods must work l
140d0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f ike the.** mallo
140e0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 c(), realloc() a
140f0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 nd free() functi
14100 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
14110 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
14120 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 .** ^SQLite guar
14130 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
14140 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
14150 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 to.** xRealloc i
14160 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 s always a value
14170 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 returned by a p
14180 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f rior call to xRo
14190 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 undup..**.** xSi
141a0 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e ze should return
141b0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
141c0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 ize of a memory
141d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 allocation.** pr
141e0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 eviously obtaine
141f0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f d from xMalloc o
14200 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 r xRealloc. The
14210 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a allocated size.
14220 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 ** is always at
14230 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 least as big as
14240 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 the requested si
14250 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 ze but may be la
14260 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rger..**.** The
14270 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 xRoundup method
14280 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 returns what wou
14290 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 ld be the alloca
142a0 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 ted size of.** a
142b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
142c0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 on given a parti
142d0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 cular requested
142e0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f size. Most memo
142f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 ry.** allocators
14300 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 round up memory
14310 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 allocations at
14320 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 least to the nex
14330 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 t multiple.** of
14340 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 8. Some alloca
14350 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f tors round up to
14360 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 a larger multip
14370 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 le or to a power
14380 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 of 2..** Every
14390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
143a0 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 n request coming
143b0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c in through [sql
143c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a ite3_malloc()].*
143d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 * or [sqlite3_re
143e0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 alloc()] first c
143f0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 alls xRoundup.
14400 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 If xRoundup retu
14410 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 rns 0, .** that
14420 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 causes the corre
14430 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 sponding memory
14440 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 allocation to fa
14450 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 il..**.** The xI
14460 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 nit method initi
14470 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 alizes the memor
14480 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 y allocator. (F
14490 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 or example,.** i
144a0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 t might allocate
144b0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 any require mut
144c0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 exes or initiali
144d0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 ze internal data
144e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 .** structures.
144f0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d The xShutdown m
14500 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
14510 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 (indirectly) by
14520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
14530 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f tdown()] and sho
14540 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 uld deallocate a
14550 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 ny resources acq
14560 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 uired.** by xIni
14570 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 t. The pAppData
14580 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 pointer is used
14590 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
145a0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e ameter to.** xIn
145b0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e it and xShutdown
145c0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 ..**.** SQLite h
145d0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 olds the [SQLITE
145e0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 _MUTEX_STATIC_MA
145f0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e STER] mutex when
14600 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 it invokes.** t
14610 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c he xInit method,
14620 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 so the xInit me
14630 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 thod need not be
14640 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 threadsafe. Th
14650 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d e.** xShutdown m
14660 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 ethod is only ca
14670 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 lled from [sqlit
14680 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 e3_shutdown()] s
14690 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 o it does.** not
146a0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 need to be thre
146b0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 adsafe either.
146c0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 For all other me
146d0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a thods, SQLite.**
146e0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
146f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
14700 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f MEM] mutex as lo
14710 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ng as the.** [SQ
14720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
14730 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 TATUS] configura
14740 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 tion option is t
14750 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a urned on (which.
14760 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 ** it is by defa
14770 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 ult) and so the
14780 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f methods are auto
14790 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c matically serial
147a0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 ized..** However
147b0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e , if [SQLITE_CON
147c0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 FIG_MEMSTATUS] i
147d0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e s disabled, then
147e0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 the other.** me
147f0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 thods must be th
14800 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 readsafe or else
14810 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 make their own
14820 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 arrangements for
14830 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f .** serializatio
14840 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
14850 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b will never invok
14860 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 e xInit() more t
14870 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 han once without
14880 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a an intervening.
14890 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 ** call to xShut
148a0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 down()..*/.typed
148b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
148c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 3_mem_methods sq
148d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
148e0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
148f0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 3_mem_methods {.
14900 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f void *(*xMallo
14910 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 c)(int);
14920 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 /* Memory alloc
14930 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a ation function *
14940 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 /. void (*xFree
14950 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
14960 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 /* Free a pri
14970 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f or allocation */
14980 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c . void *(*xReal
14990 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b loc)(void*,int);
149a0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 /* Resize an a
149b0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
149c0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 nt (*xSize)(void
149d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
149e0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 Return the size
149f0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f of an allocatio
14a00 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f n */. int (*xRo
14a10 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 undup)(int);
14a20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 /* Round u
14a30 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 p request size t
14a40 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a o allocation siz
14a50 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e e */. int (*xIn
14a60 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 it)(void*);
14a70 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c /* Initial
14a80 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
14a90 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
14aa0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 id (*xShutdown)(
14ab0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 void*); /*
14ac0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 Deinitialize the
14ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
14ae0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 r */. void *pAp
14af0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
14b00 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e /* Argumen
14b10 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 t to xInit() and
14b20 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a xShutdown() */.
14b30 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
14b40 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f EF: Configuratio
14b50 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 n Options.** KEY
14b60 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 WORDS: {configur
14b70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a ation option}.**
14b80 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
14b90 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
14ba0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
14bb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14bc0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
14bd0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
14be0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
14bf0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
14c00 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
14c10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
14c20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14c30 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
14c40 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
14c50 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
14c60 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
14c70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14c80 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
14c90 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
14ca0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
14cb0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
14cc0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
14cd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 ite3_config()] t
14ce0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
14cf0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
14d00 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ked. The [sqlit
14d10 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
14d20 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
14d30 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
14d40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
14d50 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
14d60 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
14d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14d80 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
14d90 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
14da0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14db0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 _SINGLETHREAD]]
14dc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14dd0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f G_SINGLETHREAD</
14de0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
14df0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
14e00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
14e10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
14e20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
14e30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
14e40 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 Single-thread.
14e50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
14e60 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 it disables.** a
14e70 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
14e80 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
14e90 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
14ea0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
14eb0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
14ec0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 thread. ^If S
14ed0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
14ee0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
14ef0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
14f00 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
14f10 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
14f20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
14f30 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
14f40 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 ssible to change
14f50 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
14f60 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 mode] from its d
14f70 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 efault.** value
14f80 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 of Single-thread
14f90 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 and so [sqlite3
14fa0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
14fb0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 return .** [SQLI
14fc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
14fd0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
14fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
14ff0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 ETHREAD.** confi
15000 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
15010 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
15030 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ITHREAD]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
15050 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 ITHREAD</dt>.**
15060 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
15070 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
15080 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
15090 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
150a0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
150b0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 mode] to Multi-t
150c0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
150d0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
150e0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
150f0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
15100 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
15110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
15120 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
15130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
15140 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
15150 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
15160 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
15170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
15180 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
15190 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
151a0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
151b0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
151c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
151d0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
151e0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
151f0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
15200 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
15210 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
15220 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
15230 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
15240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
15250 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
15260 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
15270 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
15280 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
15290 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
152a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
152b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
152c0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
152d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
152e0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 set the Multi-t
152f0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 hread [threading
15300 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
15310 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
15320 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
15330 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
15340 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
15350 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
15360 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 MULTITHREAD conf
15370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
15380 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
15390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
153a0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 IALIZED]] <dt>SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
153c0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c ALIZED</dt>.** <
153d0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
153e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
153f0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
15400 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
15410 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
15420 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a ode] to Serializ
15430 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 ed. In other wor
15440 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ds, this option
15450 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
15460 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
15470 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
15480 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
15490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
154a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
154b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
154c0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
154d0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
154e0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
154f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
15500 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
15510 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
15520 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
15530 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
15540 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
15550 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
15560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
15570 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
15580 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
15590 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
155a0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
155b0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
155c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
155d0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
155e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
155f0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
15600 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
15610 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
15620 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
15630 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
15640 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
15650 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
15660 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
15670 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
15680 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
15690 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 ot possible to s
156a0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 et the Serialize
156b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
156c0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 e] and.** [sqlit
156d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
156e0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
156f0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 _ERROR] if calle
15700 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
15710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
15720 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 ALIZED configura
15730 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
15740 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
15750 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d _CONFIG_MALLOC]]
15760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15770 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a IG_MALLOC</dt>.*
15780 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
15790 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
157a0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
157b0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ch is a pointer
157c0 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 to an.** instanc
157d0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
157e0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
157f0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
15800 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
15810 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
15820 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
15830 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
15840 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
15850 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 in place of.**
15860 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
15870 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 ation routines b
15880 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 uilt into SQLite
15890 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 .)^ ^SQLite make
158a0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 s.** its own pri
158b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
158c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
158d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
158e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a hods] structure.
158f0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 ** before the [s
15900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
15910 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f call returns.</
15920 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15930 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
15940 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
15950 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
15960 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
15970 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
15980 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15990 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
159a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
159b0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
159c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
159d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
159e0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
159f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 mem_methods].**
15a00 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
15a10 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
15a20 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
15a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15a40 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 routines.)^.**
15a50 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 This option can
15a60 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c be used to overl
15a70 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 oad the default
15a80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
15a90 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
15aa0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 th a wrapper tha
15ab0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 t simulations me
15ac0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15ad0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 failure or.** tr
15ae0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 acks memory usag
15af0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 e, for example.
15b00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
15b20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 TATUS]] <dt>SQLI
15b30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
15b40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TUS</dt>.** <dd>
15b50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
15b60 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d kes single argum
15b70 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c ent of type int,
15b80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
15b90 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 a .** boolean, w
15ba0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 hich enables or
15bb0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c disables the col
15bc0 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 lection of memor
15bd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a y allocation .**
15be0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 statistics. ^(W
15bf0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 hen memory alloc
15c00 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
15c10 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 are disabled, t
15c20 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 he .** following
15c30 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
15c40 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 es become non-op
15c50 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 erational:.**
15c60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b <ul>.** <li> [
15c70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
15c80 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e sed()].** <li>
15c90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
15ca0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a _highwater()].**
15cb0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
15cc0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
15cd0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 64()].** <li>
15ce0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 [sqlite3_status(
15cf0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a )].** </ul>)^.
15d00 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ** ^Memory alloc
15d10 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
15d20 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 are enabled by
15d30 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 default unless S
15d40 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 QLite is.** comp
15d50 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 iled with [SQLIT
15d60 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 E_DEFAULT_MEMSTA
15d70 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 TUS]=0 in which
15d80 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 case memory.** a
15d90 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
15da0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 tics are disable
15db0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
15dc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
15dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
15de0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ATCH]] <dt>SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
15e00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15e10 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 his option speci
15e20 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
15e30 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 mory buffer that
15e40 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
15e50 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d for.** scratch m
15e60 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 emory. There ar
15e70 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
15e80 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e s: A pointer an
15e90 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 8-byte.** align
15ea0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 ed memory buffer
15eb0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
15ec0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 scratch allocati
15ed0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 ons will be.** d
15ee0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f rawn, the size o
15ef0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 f each scratch a
15f00 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a llocation (sz),.
15f10 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d ** and the maxim
15f20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 um number of scr
15f30 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
15f40 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a (N). The sz.**
15f50 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
15f60 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 e a multiple of
15f70 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 16..** The first
15f80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 argument must b
15f90 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
15fa0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 n 8-byte aligned
15fb0 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 buffer.** of at
15fc0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
15fd0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 s of memory..**
15fe0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
15ff0 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 no more than tw
16000 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 o scratch buffer
16010 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 s per thread. S
16020 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 o.** N should be
16030 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 set to twice th
16040 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d e expected maxim
16050 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 um number of thr
16060 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 eads..** ^SQLite
16070 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 will never requ
16080 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 ire a scratch bu
16090 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 ffer that is mor
160a0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 e than 6.** time
160b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 s the database p
160c0 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 age size. ^If SQ
160d0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 Lite needs needs
160e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 additional.** s
160f0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 cratch memory be
16100 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f yond what is pro
16110 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f vided by this co
16120 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
16130 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 on, then .** [sq
16140 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
16150 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 will be used to
16160 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 obtain the memor
16170 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a y needed.</dd>.*
16180 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d NFIG_PAGECACHE]]
161a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
161b0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 IG_PAGECACHE</dt
161c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
161d0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
161e0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
161f0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
16200 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a ite can use for.
16210 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
16220 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 page cache with
16230 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 the default page
16240 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
16250 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 ation. .** This
16260 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 configuration s
16270 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
16280 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 d if an applicat
16290 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a ion-define page.
162a0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ** cache impleme
162b0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 ntation is loade
162c0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 d using the SQLI
162d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
162e0 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 2 option..** The
162f0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
16300 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
16310 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 ption: A pointer
16320 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e to 8-byte align
16330 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 ed.** memory, th
16340 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 e size of each p
16350 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c age buffer (sz),
16360 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
16370 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a of pages (N)..**
16380 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 The sz argument
16390 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 should be the s
163a0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 ize of the large
163b0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 st database page
163c0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 .** (a power of
163d0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 two between 512
163e0 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 and 32768) plus
163f0 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 a little extra f
16400 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 or each.** page
16410 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 header. ^The pa
16420 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 ge header size i
16430 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 s 20 to 40 bytes
16440 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a depending on.**
16450 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 the host archit
16460 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 ecture. ^It is
16470 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
16480 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
16490 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 memory,.** to ma
164a0 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 ke sz a little t
164b0 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 oo large. The f
164c0 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
164d0 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f should point to
164e0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f an allocation o
164f0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
16500 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e bytes of memory.
16510 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
16520 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
16530 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
16540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
16550 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a o satisfy its.**
16560 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f memory needs fo
16570 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 r the first N pa
16580 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 ges that it adds
16590 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 to cache. ^If
165a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
165b0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
165c0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
165d0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
165e0 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e d by this option
165f0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
16600 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
16610 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 3_malloc()] for
16620 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 the additional s
16630 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a torage space..**
16640 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 The pointer in
16650 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
16660 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c nt must.** be al
16670 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
16680 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 te boundary or s
16690 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
166a0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 or of SQLite.**
166b0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 will be undefine
166c0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b d.</dd>.**.** [[
166d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
166e0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AP]] <dt>SQLITE_
166f0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e CONFIG_HEAP</dt>
16700 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
16710 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
16720 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
16730 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
16740 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 te will use.** f
16750 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
16760 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c namic memory all
16770 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 ocation needs be
16780 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 yond those provi
16790 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 ded.** for by [S
167a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
167b0 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 ATCH] and [SQLIT
167c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
167d0 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 HE]..** There ar
167e0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
167f0 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 s: An 8-byte ali
16800 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 gned pointer to
16810 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 the memory,.** t
16820 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
16830 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 es in the memory
16840 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 buffer, and the
16850 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
16860 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 ion size..** ^If
16870 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 the first point
16880 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 er (the memory p
16890 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c ointer) is NULL,
168a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 then SQLite rev
168b0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 erts.** to using
168c0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d its default mem
168d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 ory allocator (t
168e0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
168f0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f () implementatio
16900 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 n),.** undoing a
16910 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 ny prior invocat
16920 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 ion of [SQLITE_C
16930 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 ONFIG_MALLOC].
16940 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 ^If the.** memor
16950 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 y pointer is not
16960 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 NULL and either
16970 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
16980 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b MEMSYS3] or.** [
16990 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
169a0 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e MSYS5] are defin
169b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 ed, then the alt
169c0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a ernative memory.
169d0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 ** allocator is
169e0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c engaged to handl
169f0 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 e all of SQLites
16a00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
16a10 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 on needs..** The
16a20 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 first pointer (
16a30 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 the memory point
16a40 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 er) must be alig
16a50 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ned to an 8-byte
16a60 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 .** boundary or
16a70 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
16a80 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ior of SQLite wi
16a90 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e ll be undefined.
16aa0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 .** The minimum
16ab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
16ac0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a is capped at 2**
16ad0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 12. Reasonable v
16ae0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 alues.** for the
16af0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
16b00 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a ion size are 2**
16b10 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 5 through 2**8.<
16b20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16b30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
16b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16b50 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a NFIG_MUTEX</dt>.
16b60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
16b70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
16b80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
16b90 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
16ba0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
16bb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
16bc0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
16bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
16be0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 e argument speci
16bf0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 fies.** alternat
16c00 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 ive low-level mu
16c10 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 tex routines to
16c20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
16c30 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f .** the mutex ro
16c40 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 utines built int
16c50 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 o SQLite.)^ ^SQ
16c60 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
16c70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 y of the.** cont
16c80 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
16c90 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
16ca0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 s] structure bef
16cb0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a ore the call to.
16cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
16cd0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e ig()] returns. ^
16ce0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
16cf0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
16d00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
16d10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
16d20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
16d30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
16d40 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
16d50 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
16d60 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
16d70 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
16d80 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
16d90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
16da0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
16db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16dc0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 MUTEX configurat
16dd0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a ion option will.
16de0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
16df0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a E_ERROR].</dd>.*
16e00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16e10 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 NFIG_GETMUTEX]]
16e20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
16e30 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a G_GETMUTEX</dt>.
16e40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
16e50 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
16e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
16e70 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
16e80 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
16e90 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
16ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
16eb0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
16ec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
16ed0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
16ee0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
16ef0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
16f00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
16f10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e utex routines.)^
16f20 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
16f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
16f40 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
16f50 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 ult mutex alloca
16f60 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
16f70 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
16f80 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 used to track mu
16f90 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 tex usage for pe
16fa0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f rformance.** pro
16fb0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e filing or testin
16fc0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 g, for example.
16fd0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
16fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
16ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
17000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
17010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
17020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
17030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
17040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
17050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
17060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
17070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
17080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
17090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
170a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
170b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 IG_GETMUTEX conf
170c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
170d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
170e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
170f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
17110 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 SIDE]] <dt>SQLIT
17120 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
17130 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
17140 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
17150 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
17160 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
17170 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 the default.**
17180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17190 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 n for the lookas
171a0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
171b0 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 ator on each.**
171c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
171d0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 tion]. The firs
171e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
171f0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
17200 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
17210 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 er slot and the
17220 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 second is the nu
17230 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 mber of.** slots
17240 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 allocated to ea
17250 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
17260 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 ection.)^ ^(Thi
17270 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
17280 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c e.** <i>default<
17290 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 /i> lookaside si
172a0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f ze. The [SQLITE_
172b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
172c0 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b DE].** verb to [
172d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
172e0 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 g()] can be used
172f0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
17300 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 ookaside.** conf
17310 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 iguration on ind
17320 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 ividual connecti
17330 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a ons.)^ </dd>.**.
17340 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
17350 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 IG_PCACHE2]] <dt
17360 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
17370 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c CACHE2</dt>.** <
17380 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
17390 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
173a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
173b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
173c0 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 ** an [sqlite3_p
173d0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 cache_methods2]
173e0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 object. This ob
173f0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 ject specifies t
17400 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
17410 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 to a custom page
17420 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
17430 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 ation.)^ ^SQLit
17440 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
17450 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 f the.** object
17460 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 and uses it for
17470 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
17480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f y allocations.</
17490 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
174a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
174b0 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 CHE2]] <dt>SQLIT
174c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
174d0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
174e0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
174f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
17500 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
17510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
17520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 ** [sqlite3_pcac
17530 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
17540 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
17550 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 ies of the curre
17560 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 nt.** page cache
17570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
17580 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
17590 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
175a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
175b0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOG]] <dt>SQLITE
175c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e _CONFIG_LOG</dt>
175d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
175e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
175f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
17600 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f arguments: a po
17610 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 inter to a.** fu
17620 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 nction with a ca
17630 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 ll signature of
17640 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e void(*)(void*,in
17650 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 t,const char*),
17660 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 .** and a pointe
17670 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 r to void. ^If t
17680 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e he function poin
17690 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c ter is not NULL,
176a0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 it is.** invoke
176b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f d by [sqlite3_lo
176c0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 g()] to process
176d0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 each logging eve
176e0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
176f0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
17700 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 is NULL, the [s
17710 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e qlite3_log()] in
17720 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 terface becomes
17730 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 a no-op..** ^The
17740 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 void pointer th
17750 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 at is the second
17760 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c argument to SQL
17770 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 ITE_CONFIG_LOG i
17780 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f s.** passed thro
17790 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
177a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
177b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
177c0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
177d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 function wheneve
177e0 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 r that function
177f0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 is invoked. ^Th
17800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
17810 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 er to.** the log
17820 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ger function is
17830 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 a copy of the fi
17840 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
17850 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
17860 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ng.** [sqlite3_l
17870 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 og()] call and i
17880 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 s intended to be
17890 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d a [result code]
178a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e or an.** [exten
178b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
178c0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 . ^The third pa
178d0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
178e0 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a o the logger is.
178f0 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 ** log message a
17900 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 fter formatting
17910 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 via [sqlite3_snp
17920 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 rintf()]..** The
17930 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 SQLite logging
17940 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
17950 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 reentrant; the
17960 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a logger function.
17970 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 ** supplied by t
17980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
17990 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 ust not invoke a
179a0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
179b0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c ace..** In a mul
179c0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c ti-threaded appl
179d0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 ication, the app
179e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
179f0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 logger.** funct
17a00 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 ion must be thre
17a10 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a adsafe. </dd>.**
17a20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
17a30 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 FIG_URI]] <dt>SQ
17a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a LITE_CONFIG_URI.
17a50 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 ** <dd> This opt
17a60 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
17a70 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
17a80 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d ype int. If non-
17a90 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 zero, then.** UR
17aa0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
17ab0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 obally enabled.
17ac0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
17ad0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 is zero, then U
17ae0 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 RI handling.** i
17af0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
17b00 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 led. If URI hand
17b10 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
17b20 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 enabled, all fi
17b30 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 lenames.** passe
17b40 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 d to [sqlite3_op
17b50 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
17b60 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c open_v2()], [sql
17b70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f ite3_open16()] o
17b80 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 r.** specified a
17b90 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 s part of [ATTAC
17ba0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 H] commands are
17bb0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
17bc0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a RIs, regardless.
17bd0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ** of whether or
17be0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 not the [SQLITE
17bf0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
17c00 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 is set when the
17c10 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
17c20 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
17c30 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 . If it is globa
17c40 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 lly disabled, fi
17c50 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f lenames are.** o
17c60 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 nly interpreted
17c70 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 as URIs if the S
17c80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 QLITE_OPEN_URI f
17c90 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
17ca0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
17cb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
17cc0 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 ened. By default
17cd0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
17ce0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
17cf0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
17d00 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
17d10 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
17d20 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
17d30 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
17d40 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
17d50 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d..**.** [[SQLIT
17d60 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d E_CONFIG_PCACHE]
17d70 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ] [[SQLITE_CONFI
17d80 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a G_GETPCACHE]].**
17d90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17da0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 IG_PCACHE and SQ
17db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
17dc0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 CACHE.** <dd> Th
17dd0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 ese options are
17de0 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f obsolete and sho
17df0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 uld not be used
17e00 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 by new code..**
17e10 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 They are retaine
17e20 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
17e30 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 compatibility bu
17e40 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 t are now no-ops
17e50 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 ..** </dl>.*/.#d
17e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17e70 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
17e80 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 1 /* nil */.#
17e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17ea0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
17eb0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 2 /* nil */.
17ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
17ed0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
17ee0 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 3 /* nil */
17ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17f00 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 CONFIG_MALLOC
17f10 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 4 /* sqlit
17f20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
17f30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17f40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
17f50 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c OC 5 /* sql
17f60 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
17f70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
17f80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
17f90 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 CH 6 /* v
17fa0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
17fb0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
17fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
17fd0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a ECACHE 7 /*
17fe0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
17ff0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
18000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
18010 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 EAP 8
18020 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 /* void*, int nB
18030 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a yte, int min */.
18040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18050 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
18060 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 9 /* boolea
18070 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
18080 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
18090 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 10 /* s
180a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
180b0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
180c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
180d0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 ETMUTEX 11
180e0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
180f0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 _methods* */./*
18100 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 previously SQLIT
18110 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c E_CONFIG_CHUNKAL
18120 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 LOC 12 which is
18130 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a now unused. */ .
18140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18150 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
18160 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 13 /* int in
18170 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
18180 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
18190 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e E 14 /* n
181a0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 o-op */.#define
181b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
181c0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f TPCACHE 15 /
181d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
181e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
181f0 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 _LOG 16
18200 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 /* xFunc, void
18210 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
18220 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 ITE_CONFIG_URI
18230 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 17 /* i
18240 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
18250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
18260 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 HE2 18 /*
18270 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
18280 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 ethods2* */.#def
18290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
182a0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 G_GETPCACHE2 1
182b0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 9 /* sqlite3_pc
182c0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a ache_methods2* *
182d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
182e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
182f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 ection Configura
18300 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a tion Options.**.
18310 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
18320 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
18330 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
18340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
18350 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
18360 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
18370 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
18380 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
18390 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
183a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
183b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
183c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
183d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
183e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
183f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
18400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
18410 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
18420 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
18430 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
18440 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
18450 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
18460 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
18470 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
18480 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
18490 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 ll worked. ^The
184a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
184b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
184c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
184d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
184e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
184f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
18500 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
18510 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
18520 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
18530 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
18540 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
18550 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
18560 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
18570 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 on takes three a
18580 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
18590 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
185a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b ne the .** [look
185b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
185c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
185d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 ation for the [d
185e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
185f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 on]..** ^The fir
18600 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 st argument (the
18610 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
18620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
18630 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a config()] is a.*
18640 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d * pointer to a m
18650 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 emory buffer to
18660 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 use for lookasid
18670 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 e memory..** ^Th
18680 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18690 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 after the SQLIT
186a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
186b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 SIDE verb.** may
186c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 be NULL in whic
186d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 h case SQLite wi
186e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a ll allocate the.
186f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ** lookaside buf
18700 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 fer itself using
18710 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
18720 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ()]. ^The second
18730 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
18740 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
18750 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
18760 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 r slot. ^The th
18770 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
18780 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
18790 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a slots. The siz
187a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 e of the buffer
187b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
187c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 ument must be gr
187d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 eater than.** or
187e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 equal to the pr
187f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 oduct of the sec
18800 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 ond and third ar
18810 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 guments. The bu
18820 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 ffer.** must be
18830 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
18840 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 byte boundary.
18850 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 ^If the second a
18860 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 rgument to.** SQ
18870 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
18880 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 OKASIDE is not a
18890 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 multiple of 8,
188a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 it is internally
188b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e .** rounded down
188c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 to the next sma
188d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ller multiple of
188e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 8. ^(The looka
188f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 side memory.** c
18900 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
18910 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
18920 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 ection can only
18930 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 be changed when
18940 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 that.** connecti
18950 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e on is not curren
18960 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 tly using lookas
18970 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 ide memory, or i
18980 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a n other words.**
18990 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 when the "curre
189a0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e nt value" return
189b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
189c0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 3_db_status](D,[
189d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
189e0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 OKASIDE],...) is
189f0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 zero..** Any at
18a00 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 tempt to change
18a10 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
18a20 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 mory configurati
18a30 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 on when lookasid
18a40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 e.** memory is i
18a50 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 n use leaves the
18a60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
18a70 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
18a80 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 urns .** [SQLITE
18a90 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a _BUSY].)^</dd>.*
18aa0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
18ab0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
18ac0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 FKEY</dt>.** <dd
18ad0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
18ae0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
18af0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 or disable the
18b00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a enforcement of.*
18b10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 * [foreign key c
18b20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 onstraints]. Th
18b30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
18b40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
18b50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
18b60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
18b70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
18b80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
18b90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
18ba0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
18bb0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 enable FK enfor
18bc0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 cement or negati
18bd0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 ve to leave FK e
18be0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e nforcement.** un
18bf0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 changed. The se
18c00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
18c10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
18c20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
18c30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
18c40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
18c50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b icate whether FK
18c60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 enforcement is
18c70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c off or on.** fol
18c80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
18c90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
18ca0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
18cb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
18cc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
18cd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 the FK enforceme
18ce0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f nt setting is no
18cf0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
18d00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
18d10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
18d20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c _ENABLE_TRIGGER<
18d30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
18d40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
18d50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
18d60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 isable [CREATE T
18d70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
18d80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f s]..** There sho
18d90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
18da0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
18db0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
18dc0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
18dd0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
18de0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 to disable trigg
18df0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ers,.** positive
18e00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 to enable trigg
18e10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ers or negative
18e20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 to leave the set
18e30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a ting unchanged..
18e40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
18e50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
18e60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
18e70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
18e80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
18e90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
18ea0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 hether triggers
18eb0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 are disabled or
18ec0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f enabled.** follo
18ed0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
18ee0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
18ef0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
18f00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
18f10 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
18f20 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e e trigger settin
18f30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
18f40 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
18f50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
18f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
18f70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
18f80 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 1001 /* vo
18f90 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 id* int int */.#
18fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
18fb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
18fc0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 EY 1002 /*
18fd0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
18ff0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
19000 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 ER 1003 /* int
19010 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a int* */.../*.**
19020 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
19030 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 e Or Disable Ext
19040 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
19050 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 es.**.** ^The sq
19060 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
19070 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f esult_codes() ro
19080 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
19090 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a disables the.**
190a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
190b0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 t codes] feature
190c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 of SQLite. ^The
190d0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
190e0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 .** codes are di
190f0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
19100 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c t for historical
19110 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
19120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
19130 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
19140 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
19150 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
19160 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
19170 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
19180 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e rt Rowid.**.** ^
19190 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e Each entry in an
191a0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 SQLite table ha
191b0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 s a unique 64-bi
191c0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 t signed.** inte
191d0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 ger key called t
191e0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 he [ROWID | "row
191f0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 id"]. ^The rowid
19200 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c is always avail
19210 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e able.** as an un
19220 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 declared column
19230 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 named ROWID, OID
19240 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 , or _ROWID_ as
19250 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a long as those.**
19260 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 names are not a
19270 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c lso used by expl
19280 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
19290 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 columns. ^If.**
192a0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 the table has a
192b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b column of type [
192c0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
192d0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 KEY] then that c
192e0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 olumn.** is anot
192f0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 her alias for th
19300 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e e rowid..**.** ^
19310 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
19320 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d urns the [rowid]
19330 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
19340 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
19350 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
19360 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f the database fro
19370 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 m the [database
19380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 connection].** i
19390 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
193a0 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 ment. ^As of SQ
193b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
193c0 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .7, this routine
193d0 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 s.** records the
193e0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 last insert row
193f0 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e id of both ordin
19400 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b ary tables and [
19410 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e virtual tables].
19420 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 .** ^If no succe
19430 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a ssful [INSERT]s.
19440 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 ** have ever occ
19450 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 urred on that da
19460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19470 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 n, zero is retur
19480 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ned..**.** ^(If
19490 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
194a0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
194b0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 ger or within a
194c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
194d0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 ** method, then
194e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
194f0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f l return the [ro
19500 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 wid] of the inse
19510 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c rted.** row as l
19520 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 ong as the trigg
19530 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
19540 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 ble method is ru
19550 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e nning..** But on
19560 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f ce the trigger o
19570 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
19580 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 method ends, the
19590 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
195a0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
195b0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 ine reverts to w
195c0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 hat it was befor
195d0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 e the trigger or
195e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c virtual.** tabl
195f0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 e method began.)
19600 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 ^.**.** ^An [INS
19610 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
19620 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
19630 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
19640 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
19650 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
19660 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
19670 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
19680 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
19690 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 routine. ^Thus
196a0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
196b0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
196c0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
196d0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
196e0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
196f0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
19700 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
19710 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
19720 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
19730 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
19740 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f ^(When INSERT O
19750 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 R REPLACE.** enc
19760 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 ounters a constr
19770 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 aint violation,
19780 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c it does not fail
19790 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 . The.** INSERT
197a0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
197b0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 mpletion after d
197c0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 eleting rows tha
197d0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 t caused.** the
197e0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c constraint probl
197f0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 em so INSERT OR
19800 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 REPLACE will alw
19810 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 ays change.** th
19820 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19830 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
19840 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 .)^.**.** ^For t
19850 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
19860 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 his routine, an
19870 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 [INSERT] is cons
19880 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 idered to.** be
19890 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 successful even
198a0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 if it is subsequ
198b0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 ently rolled bac
198c0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 k..**.** This fu
198d0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 nction is access
198e0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 ible to SQL stat
198f0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a ements via the.*
19900 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 * [last_insert_r
19910 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 owid() SQL funct
19920 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
19930 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
19940 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
19950 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
19960 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
19970 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
19980 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
19990 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
199a0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
199b0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
199c0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
199d0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
199e0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
199f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19a00 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
19a10 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
19a20 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
19a30 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
19a40 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
19a50 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
19a60 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
19a70 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 t [rowid]..*/.SQ
19a80 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
19a90 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c _int64 sqlite3_l
19aa0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
19ab0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
19ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 ** CAPI3REF: Cou
19ad0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 nt The Number Of
19ae0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a Rows Modified.*
19af0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
19b00 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
19b10 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 number of databa
19b20 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 se rows that wer
19b30 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 e changed.** or
19b40 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 inserted or dele
19b50 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 ted by the most
19b60 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
19b70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
19b80 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 .** on the [data
19b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
19ba0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
19bb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
19bc0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 r..** ^(Only cha
19bd0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 nges that are di
19be0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 rectly specified
19bf0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d by the [INSERT]
19c00 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f , [UPDATE],.** o
19c10 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
19c20 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 ment are counted
19c30 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 . Auxiliary cha
19c40 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a nges caused by.*
19c50 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 * triggers or [f
19c60 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
19c70 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ns] are not coun
19c80 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a ted.)^ Use the.*
19c90 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c * [sqlite3_total
19ca0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 _changes()] func
19cb0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 tion to find the
19cc0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 total number of
19cd0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c changes.** incl
19ce0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 uding changes ca
19cf0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 used by triggers
19d00 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 and foreign key
19d10 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 actions..**.**
19d20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 ^Changes to a vi
19d30 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 ew that are simu
19d40 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 lated by an [INS
19d50 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d TEAD OF trigger]
19d60 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
19d70 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 ted. Only real
19d80 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 table changes ar
19d90 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a e counted..**.**
19da0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 ^(A "row change
19db0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f " is a change to
19dc0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 a single row of
19dd0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a a single table.
19de0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 ** caused by an
19df0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 INSERT, DELETE,
19e00 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d or UPDATE statem
19e10 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a ent. Rows that.
19e20 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 ** are changed a
19e30 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f s side effects o
19e40 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 f [REPLACE] cons
19e50 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
19e60 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 n,.** rollback,
19e70 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
19e80 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 , [DROP TABLE],
19e90 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a or by any other.
19ea0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f ** mechanisms do
19eb0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 not count as di
19ec0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 rect row changes
19ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 .)^.**.** A "tri
19ee0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 gger context" is
19ef0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 a scope of exec
19f00 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e ution that begin
19f10 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 s and.** ends wi
19f20 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 th the script of
19f30 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 a [CREATE TRIGG
19f40 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a ER | trigger]. .
19f50 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 ** Most SQL stat
19f60 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 ements are.** ev
19f70 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 aluated outside
19f80 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 of any trigger.
19f90 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f This is the "to
19fa0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 p level".** trig
19fb0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 ger context. If
19fc0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 a trigger fires
19fd0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
19fe0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 vel, a.** new tr
19ff0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 igger context is
1a000 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 entered for the
1a010 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 duration of tha
1a020 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 t one.** trigger
1a030 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 . Subtriggers c
1a040 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 reate subcontext
1a050 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 s for their dura
1a060 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c tion..**.** ^Cal
1a070 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 ling [sqlite3_ex
1a080 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ec()] or [sqlite
1a090 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 3_step()] recurs
1a0a0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f ively does.** no
1a0b0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 t create a new t
1a0c0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a rigger context..
1a0d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1a0e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
1a0f0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 number of direc
1a100 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e t row changes in
1a110 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the.** most rec
1a120 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
1a130 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 TE, or DELETE st
1a140 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
1a150 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 he same.** trigg
1a160 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a er context..**.*
1a170 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 * ^Thus, when ca
1a180 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f lled from the to
1a190 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 p level, this fu
1a1a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
1a1b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
1a1c0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
1a1d0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
1a1e0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
1a1f0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 LETE.** that als
1a200 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 o occurred at th
1a210 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 e top level. ^(
1a220 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 Within the body
1a230 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a of a trigger,.**
1a240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
1a250 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
1a260 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 can be called t
1a270 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
1a280 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 r of.** changes
1a290 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
1a2a0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 ntly completed I
1a2b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
1a2c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
1a2d0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
1a2e0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d body of the sam
1a2f0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f e trigger..** Ho
1a300 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 wever, the numbe
1a310 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 r returned does
1a320 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
1a330 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 ges.** caused by
1a340 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e subtriggers sin
1a350 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 ce those have th
1a360 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e eir own context.
1a370 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
1a380 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 o the [sqlite3_t
1a390 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
1a3a0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
1a3b0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
1a3c0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
1a3d0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
1a3e0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
1a3f0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
1a400 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
1a410 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
1a420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1a430 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
1a440 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1a450 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
1a460 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
1a470 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 rned.** is unpre
1a480 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
1a490 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
1a4a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1a4b0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 qlite3_changes(s
1a4c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1a4d0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c CAPI3REF: Total
1a4e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
1a4f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
1a500 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
1a510 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
1a520 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 of row changes
1a530 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 caused by [INSER
1a540 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 T],.** [UPDATE]
1a550 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 or [DELETE] stat
1a560 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 ements since the
1a570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1a580 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 ction] was opene
1a590 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e d..** ^(The coun
1a5a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 t returned by sq
1a5b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
1a5c0 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 ges() includes a
1a5d0 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 ll changes.** fr
1a5e0 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 om all [CREATE T
1a5f0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
1a600 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 ] contexts and c
1a610 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a hanges made by.*
1a620 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
1a630 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 ctions]. However
1a640 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 ,.** the count d
1a650 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
1a660 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 changes used to
1a670 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 implement [REPLA
1a680 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c CE] constraints,
1a690 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 .** do rollbacks
1a6a0 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 or ABORT proces
1a6b0 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 sing, or [DROP T
1a6c0 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 ABLE] processing
1a6d0 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 . The.** count
1a6e0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
1a6f0 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 rows of views t
1a700 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 hat fire an [INS
1a710 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d TEAD OF trigger]
1a720 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 ,.** though if t
1a730 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 he INSTEAD OF tr
1a740 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e igger makes chan
1a750 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 ges of its own,
1a760 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a those changes .*
1a770 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e * are counted.)^
1a780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1a790 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1a7a0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 function counts
1a7b0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 the changes as
1a7c0 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 soon as.** the s
1a7d0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 tatement that ma
1a7e0 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 kes them is comp
1a7f0 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 leted (when the
1a800 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 statement handle
1a810 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f .** is passed to
1a820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1a830 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
1a840 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a inalize()])..**.
1a850 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
1a860 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
1a870 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 ()] interface, t
1a880 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 he.** [count_cha
1a890 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e nges pragma], an
1a8a0 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 d the [total_cha
1a8b0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
1a8c0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
1a8d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
1a8e0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
1a8f0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
1a900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1a910 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 * while [sqlite3
1a920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1a930 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
1a940 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 n the value.** r
1a950 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 eturned is unpre
1a960 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
1a970 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
1a980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1a990 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1a9a0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
1a9b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a9c0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
1a9d0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a g-Running Query.
1a9e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1a9f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
1aa00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
1aa10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
1aa20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
1aa30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
1aa40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
1aa50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
1aa60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
1aa70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
1aa80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
1aa90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
1aaa0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
1aab0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
1aac0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
1aad0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
1aae0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
1aaf0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
1ab00 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 ^It is safe to
1ab10 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
1ab20 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
1ab30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
1ab40 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
1ab50 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
1ab60 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
1ab70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
1ab80 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
1ab90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
1aba0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
1abb0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
1abc0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
1abd0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
1abe0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
1abf0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1ac00 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
1ac10 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 ** ^If an SQL op
1ac20 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
1ac30 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
1ac40 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
1ac50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
1ac60 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
1ac70 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
1ac80 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
1ac90 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
1aca0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
1acb0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
1acc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
1acd0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 **.** ^An SQL op
1ace0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 eration that is
1acf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c interrupted will
1ad00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1ad10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e INTERRUPT]..** ^
1ad20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
1ad30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
1ad40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
1ad50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
1ad60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
1ad70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
1ad80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
1ad90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
1ada0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
1adb0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
1adc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
1add0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1ade0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 _interrupt(D) ca
1adf0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 ll is in effect
1ae00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e until all curren
1ae10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 tly running.** S
1ae20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e QL statements on
1ae30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1ae40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 ction] D complet
1ae50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c e. ^Any new SQL
1ae60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
1ae70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
1ae80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
1ae90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
1aea0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ll and before th
1aeb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 e .** running st
1aec0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 atements reaches
1aed0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 zero are interr
1aee0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 upted as if they
1aef0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e had been.** run
1af00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 ning prior to th
1af10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1af20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 upt() call. ^Ne
1af30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
1af40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
1af50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 rted after the r
1af60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
1af70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a count reaches z
1af80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 ero are.** not e
1af90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 ffected by the s
1afa0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1afb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 ()..** ^A call t
1afc0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 o sqlite3_interr
1afd0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 upt(D) that occu
1afe0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 rs when there ar
1aff0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 e no running.**
1b000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
1b010 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 s a no-op and ha
1b020 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 s no effect on S
1b030 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1b040 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
1b050 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
1b060 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1b070 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a call returns..**
1b080 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
1b090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
1b0a0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
1b0b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b0c0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
1b0d0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
1b0e0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
1b0f0 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 en..*/.SQLITE_AP
1b100 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 I void sqlite3_i
1b110 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 nterrupt(sqlite3
1b120 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1b130 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
1b140 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
1b150 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a nt Is Complete.*
1b160 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b170 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 nes are useful d
1b180 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 uring command-li
1b190 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
1b1a0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
1b1b0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
1b1c0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 d text seems to
1b1d0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 form a complete
1b1e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 SQL statement or
1b1f0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 .** if additiona
1b200 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 l input is neede
1b210 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 d before sending
1b220 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a the text into.*
1b230 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 * SQLite for par
1b240 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f sing. ^These ro
1b250 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
1b260 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
1b270 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
1b280 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
1b290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
1b2a0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ^A statement is
1b2b0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 judged to be.**
1b2c0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 complete if it e
1b2d0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 nds with a semic
1b2e0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 olon token and i
1b2f0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f s not a prefix o
1b300 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d f a.** well-form
1b310 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ed CREATE TRIGGE
1b320 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 R statement. ^S
1b330 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
1b340 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
1b350 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
1b360 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
1b370 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
1b380 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
1b390 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
1b3a0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
1b3b0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
1b3c0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
1b3d0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
1b3e0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
1b3f0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
1b400 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
1b410 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 nator. ^Whitesp
1b420 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 ace.** and comme
1b430 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 nts that follow
1b440 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f the final semico
1b450 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e lon are ignored.
1b460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1b470 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 utines return 0
1b480 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
1b490 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 is incomplete.
1b4a0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 ^If a.** memory
1b4b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
1b4c0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e s, then SQLITE_N
1b4d0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 OMEM is returned
1b4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
1b4f0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
1b500 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
1b510 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
1b520 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
1b530 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
1b540 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
1b550 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 ** ^(If SQLite h
1b560 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
1b570 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
1b580 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
1b590 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
1b5a0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
1b5b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
1b5c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
1b5d0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
1b5e0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
1b5f0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
1b600 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
1b610 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
1b620 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
1b630 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
1b640 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
1b650 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1b660 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
1b670 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
1b680 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
1b690 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
1b6a0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a is complete.)^.*
1b6b0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
1b6c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
1b6d0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
1b6e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1b6f0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
1b700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ..**.** The inpu
1b710 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
1b720 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
1b730 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
1b740 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
1b750 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
1b760 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a byte order..*/.
1b770 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1b780 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
1b790 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
1b7a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
1b7b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1b7c0 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
1b7d0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
1b7e0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
1b7f0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
1b800 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
1b810 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 Errors.**.** ^T
1b820 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 his routine sets
1b830 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1b840 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 tion that might
1b850 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
1b860 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 ver.** an attemp
1b870 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 t is made to ope
1b880 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
1b890 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 le that another
1b8a0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f thread.** or pro
1b8b0 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e cess has locked.
1b8c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 .**.** ^If the b
1b8d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
1b8e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 NULL, then [SQLI
1b8f0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
1b900 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
1b910 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 D].** is returne
1b920 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
1b930 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
1b940 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 the lock. ^If t
1b950 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1b960 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
1b970 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
1b980 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f ck might be invo
1b990 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
1b9a0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 uments..**.** ^T
1b9b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1b9c0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 t to the busy ha
1b9d0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 ndler is a copy
1b9e0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 of the void* poi
1b9f0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 nter which.** is
1ba00 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
1ba10 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
1ba20 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 usy_handler().
1ba30 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
1ba40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 ment to.** the b
1ba50 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy handler call
1ba60 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 back is the numb
1ba70 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
1ba80 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1ba90 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
1baa0 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c voked for this l
1bab0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e ocking event. ^
1bac0 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 If the.** busy c
1bad0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1bae0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 0, then no addit
1baf0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 ional attempts a
1bb00 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 re made to.** ac
1bb10 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
1bb20 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 e and [SQLITE_BU
1bb30 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
1bb40 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 OERR_BLOCKED] is
1bb50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 returned..** ^I
1bb60 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
1bb70 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
1bb80 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
1bb90 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
1bba0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
1bbb0 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e abase for readin
1bbc0 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 g and the cycle
1bbd0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 repeats..**.** T
1bbe0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 he presence of a
1bbf0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f busy handler do
1bc00 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 es not guarantee
1bc10 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 that it will be
1bc20 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
1bc30 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 there is lock c
1bc40 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 ontention. ^If S
1bc50 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 QLite determines
1bc60 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 that invoking t
1bc70 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c he busy.** handl
1bc80 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 er could result
1bc90 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 in a deadlock, i
1bca0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 t will go ahead
1bcb0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
1bcc0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b TE_BUSY].** or [
1bcd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
1bce0 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 CKED] instead of
1bcf0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
1bd00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
1bd10 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
1bd20 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
1bd30 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1bd40 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
1bd50 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
1bd60 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
1bd70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
1bd80 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
1bd90 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1bda0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
1bdb0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
1bdc0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
1bdd0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
1bde0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
1bdf0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
1be00 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
1be10 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1be20 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1be30 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
1be40 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
1be50 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
1be60 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1be70 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
1be80 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
1be90 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
1bea0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
1beb0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
1bec0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
1bed0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
1bee0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
1bef0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
1bf00 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
1bf10 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
1bf20 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
1bf30 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1bf40 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
1bf50 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
1bf60 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
1bf70 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
1bf80 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
1bf90 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
1bfa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1bfb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ..**.** ^The [SQ
1bfc0 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 LITE_BUSY] error
1bfd0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f is converted to
1bfe0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
1bff0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 LOCKED].** when
1c000 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 SQLite is in the
1c010 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 middle of a lar
1c020 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 ge transaction w
1c030 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 here all the.**
1c040 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 changes will not
1c050 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e fit into the in
1c060 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 -memory cache.
1c070 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 SQLite will.** a
1c080 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 lready hold a RE
1c090 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 SERVED lock on t
1c0a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
1c0b0 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a , but it needs.*
1c0c0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 * to promote thi
1c0d0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 s lock to EXCLUS
1c0e0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 IVE so that it c
1c0f0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a an spill cache.*
1c100 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 * pages into the
1c110 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
1c120 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 ithout harm to c
1c130 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 oncurrent.** rea
1c140 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 ders. ^If it is
1c150 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
1c160 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
1c170 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
1c180 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
1c190 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
1c1a0 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
1c1b0 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
1c1c0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
1c1d0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
1c1e0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
1c1f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
1c200 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
1c210 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
1c220 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 _BLOCKED]. ^Thi
1c230 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f s error code pro
1c240 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 motion.** forces
1c250 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f an automatic ro
1c260 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 llback of the ch
1c270 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a anges. See the.
1c280 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 ** <a href="/cvs
1c290 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 trac/wiki?p=Corr
1c2a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
1c2b0 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f usyError">.** Co
1c2c0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
1c2d0 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 gBusyError</a> w
1c2e0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 iki page for a d
1c2f0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 iscussion of why
1c300 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f .** this is impo
1c310 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 rtant..**.** ^(T
1c320 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
1c330 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
1c340 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 andler defined f
1c350 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 or each.** [data
1c360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1c370 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 . Setting a new
1c380 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c busy handler cl
1c390 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 ears any.** prev
1c3a0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c iously set handl
1c3b0 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 er.)^ ^Note tha
1c3c0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
1c3d0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1c3e0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 )].** will also
1c3f0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 set or clear the
1c400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1c410 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
1c420 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
1c430 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
1c440 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
1c450 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
1c460 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1c470 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1c480 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 handler. Any s
1c490 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 uch actions.** r
1c4a0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
1c4b0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 ed behavior..**
1c4c0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c .** A busy handl
1c4d0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 er must not clos
1c4e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
1c4f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 onnection.** or
1c500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1c510 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 ent] that invoke
1c520 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
1c530 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 er..*/.SQLITE_AP
1c540 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 I int sqlite3_bu
1c550 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 sy_handler(sqlit
1c560 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 e3*, int(*)(void
1c570 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a *,int), void*);.
1c580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1c590 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
1c5a0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 out.**.** ^This
1c5b0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
1c5c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1c5d0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
1c5e0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 ler] that sleeps
1c5f0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 .** for a specif
1c600 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 ied amount of ti
1c610 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 me when a table
1c620 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 is locked. ^The
1c630 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c handler.** will
1c640 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 sleep multiple
1c650 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c times until at l
1c660 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
1c670 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
1c680 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d ng.** have accum
1c690 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 ulated. ^After
1c6a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
1c6b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
1c6c0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 eeping,.** the h
1c6d0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 andler returns 0
1c6e0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 which causes [s
1c6f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 qlite3_step()] t
1c700 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c o return.** [SQL
1c710 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 ITE_BUSY] or [SQ
1c720 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
1c730 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ED]..**.** ^Call
1c740 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ing this routine
1c750 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e with an argumen
1c760 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 t less than or e
1c770 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 qual to zero.**
1c780 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 turns off all bu
1c790 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a sy handlers..**.
1c7a0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1c7b0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1c7c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 busy handler for
1c7d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
1c7e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c7f0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 ction] any any g
1c800 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 iven moment. If
1c810 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 another busy ha
1c820 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 ndler.** was def
1c830 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 ined (using [sq
1c840 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1c850 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 er()]) prior to
1c860 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 calling.** this
1c870 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 routine, that ot
1c880 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
1c890 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a is cleared.)^.*
1c8a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1c8b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 sqlite3_busy_ti
1c8c0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 meout(sqlite3*,
1c8d0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int ms);../*.**
1c8e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e CAPI3REF: Conven
1c8f0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 ience Routines F
1c900 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 or Running Queri
1c910 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 es.**.** This is
1c920 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 a legacy interf
1c930 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 ace that is pres
1c940 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 erved for backwa
1c950 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1c960 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 y..** Use of thi
1c970 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e s interface is n
1c980 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a ot recommended..
1c990 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e **.** Definition
1c9a0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 : A <b>result ta
1c9b0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 ble</b> is memor
1c9c0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 y data structure
1c9d0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a created by the.
1c9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
1c9f0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 table()] interfa
1ca00 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 ce. A result ta
1ca10 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a ble records the.
1ca20 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 ** complete quer
1ca30 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f y results from o
1ca40 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 ne or more queri
1ca50 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 es..**.** The ta
1ca60 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 ble conceptually
1ca70 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 has a number of
1ca80 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e rows and column
1ca90 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 s. But.** these
1caa0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 numbers are not
1cab0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 part of the res
1cac0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 ult table itself
1cad0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 . These.** numb
1cae0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 ers are obtained
1caf0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 separately. Le
1cb00 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 t N be the numbe
1cb10 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 r of rows.** and
1cb20 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 M be the number
1cb30 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a of columns..**.
1cb40 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1cb50 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 e is an array of
1cb60 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 pointers to zer
1cb70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1cb80 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 -8 strings..** T
1cb90 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d here are (N+1)*M
1cba0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 elements in the
1cbb0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 array. The fir
1cbc0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f st M pointers po
1cbd0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 int.** to zero-t
1cbe0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
1cbf0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 s that contain
1cc00 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 the names of the
1cc10 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 columns..** The
1cc20 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 remaining entri
1cc30 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 es all point to
1cc40 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 query results.
1cc50 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 NULL values resu
1cc60 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f lt.** in NULL po
1cc70 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 inters. All oth
1cc80 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e er values are in
1cc90 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 their UTF-8 zer
1cca0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
1ccb0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
1ccc0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 ation as returne
1ccd0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
1cce0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
1ccf0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1cd00 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 le might consist
1cd10 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 of one or more
1cd20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1cd30 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 ns..** It is not
1cd40 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 safe to pass a
1cd50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 result table dir
1cd60 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 ectly to [sqlite
1cd70 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 3_free()]..** A
1cd80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f result table sho
1cd90 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 uld be deallocat
1cda0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1cdb0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 3_free_table()].
1cdc0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 .**.** ^(As an e
1cdd0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 xample of the re
1cde0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 sult table forma
1cdf0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 t, suppose a que
1ce00 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 ry result.** is
1ce10 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1ce20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1ce30 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 re>.** Na
1ce40 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a me | Age.
1ce50 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d ** ------
1ce60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1ce70 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 -.** Alic
1ce80 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 e | 43.**
1ce90 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 Bob
1cea0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 | 28.**
1ceb0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 Cindy |
1cec0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 21.** </pre></bl
1ced0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1cee0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f There are two co
1cef0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 lumn (M==2) and
1cf00 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 three rows (N==3
1cf10 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 ). Thus the.**
1cf20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 result table has
1cf30 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 8 entries. Sup
1cf40 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 pose the result
1cf50 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a table is stored.
1cf60 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e ** in an array n
1cf70 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 ames azResult.
1cf80 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f Then azResult ho
1cf90 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 lds this content
1cfa0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1cfb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
1cfc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1cfd0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a ;0] = "Name";.**
1cfe0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1cff0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b [1] = "Age";
1d000 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1d010 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c ult[2] = "Al
1d020 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ice";.**
1d030 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 azResult[3]
1d040 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 = "43";.**
1d050 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 azResult[4
1d060 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 ] = "Bob";.**
1d070 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d080 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 1;5] = "28";.**
1d090 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1d0a0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 #91;6] = "Cindy"
1d0b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1d0c0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 sult[7] = "2
1d0d0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 1";.** </pre></b
1d0e0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a lockquote>)^.**.
1d0f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1d100 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 get_table() func
1d110 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f tion evaluates o
1d120 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 ne or more.** se
1d130 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
1d140 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
1d150 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 in the zero-ter
1d160 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a minated UTF-8.**
1d170 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 string of its 2
1d180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
1d190 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c returns a resul
1d1a0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a t table to the.*
1d1b0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 * pointer given
1d1c0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d in its 3rd param
1d1d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 eter..**.** Afte
1d1e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
1d1f0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 n has finished w
1d200 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 ith the result f
1d210 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f rom sqlite3_get_
1d220 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d table(),.** it m
1d230 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 ust pass the res
1d240 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 ult table pointe
1d250 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 r to sqlite3_fre
1d260 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 e_table() in ord
1d270 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 er to.** release
1d280 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 the memory that
1d290 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 was malloced.
1d2a0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 Because of the w
1d2b0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ay the.** [sqlit
1d2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 e3_malloc()] hap
1d2d0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 pens within sqli
1d2e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
1d2f0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 the calling.**
1d300 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f function must no
1d310 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 t try to call [s
1d320 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 qlite3_free()] d
1d330 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a irectly. Only.*
1d340 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f * [sqlite3_free_
1d350 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 table()] is able
1d360 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 to release the
1d370 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 memory properly
1d380 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a and safely..**.*
1d390 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
1d3a0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 t_table() interf
1d3b0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ace is implement
1d3c0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 ed as a wrapper
1d3d0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
1d3e0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 e3_exec()]. The
1d3f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d400 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 le() routine doe
1d410 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 s not have acces
1d420 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 s.** to any inte
1d430 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 rnal data struct
1d440 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ures of SQLite.
1d450 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 It uses only th
1d460 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 e public.** inte
1d470 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 rface defined he
1d480 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 re. As a conseq
1d490 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 uence, errors th
1d4a0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a at occur in the.
1d4b0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 ** wrapper layer
1d4c0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 outside of the
1d4d0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 internal [sqlite
1d4e0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 3_exec()] call a
1d4f0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 re not.** reflec
1d500 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e ted in subsequen
1d510 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
1d520 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f te3_errcode()] o
1d530 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 r.** [sqlite3_er
1d540 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 rmsg()]..*/.SQLI
1d550 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1d560 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 e3_get_table(.
1d570 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
1d580 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e /* An open
1d590 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
1d5a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
1d5b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
1d5c0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
1d5d0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 char ***pazResu
1d5e0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 lt, /* Result
1d5f0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a s of the query *
1d600 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 /. int *pnRow,
1d610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d /* Num
1d620 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f ber of result ro
1d630 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ws written here
1d640 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 */. int *pnColu
1d650 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 mn, /* Nu
1d660 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 mber of result c
1d670 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 olumns written h
1d680 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ere */. char **
1d690 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f pzErrmsg /
1d6a0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
1d6b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 ten here */.);.S
1d6c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
1d6d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1d6e0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 e(char **result)
1d6f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1d700 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 F: Formatted Str
1d710 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e ing Printing Fun
1d720 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
1d730 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
1d740 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 work-alikes of t
1d750 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 he "printf()" fa
1d760 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
1d770 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 s.** from the st
1d780 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1d790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1d7a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
1d7b0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
1d7c0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
1d7d0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
1d7e0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
1d7f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1d800 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1d810 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
1d820 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
1d830 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
1d840 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
1d850 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
1d860 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
1d870 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
1d880 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
1d890 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
1d8a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
1d8b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1d8c0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
1d8d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
1d8e0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
1d8f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
1d900 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 ite3_snprintf()
1d910 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
1d920 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 ar to "snprintf(
1d930 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 )" from.** the s
1d940 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1d950 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 y. The result i
1d960 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 s written into t
1d970 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 he.** buffer sup
1d980 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 plied as the sec
1d990 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 ond parameter wh
1d9a0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 ose size is give
1d9b0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 n by.** the firs
1d9c0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 t parameter. Not
1d9d0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 e that the order
1d9e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 of the.** first
1d9f0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 two parameters
1da00 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d is reversed from
1da10 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 snprintf().)^
1da20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
1da30 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
1da40 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
1da50 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
1da60 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
1da70 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1da80 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f ty. ^(Note also
1da90 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e that sqlite3_sn
1daa0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 printf().** retu
1dab0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1dac0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 its buffer inst
1dad0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ead of the numbe
1dae0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 r of.** characte
1daf0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 rs actually writ
1db00 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 ten into the buf
1db10 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 fer.)^ We admit
1db20 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d that.** the num
1db30 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
1db40 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 s written would
1db50 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c be a more useful
1db60 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
1db70 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 but we cannot c
1db80 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d hange the implem
1db90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
1dba0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1dbb0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 * now without br
1dbc0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 eaking compatibi
1dbd0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 lity..**.** ^As
1dbe0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
1dbf0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
1dc00 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
1dc10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1dc20 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
1dc30 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
1dc40 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
1dc50 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
1dc60 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
1dc70 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
1dc80 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
1dc90 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
1dca0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
1dcb0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
1dcc0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
1dcd0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
1dce0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
1dcf0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
1dd00 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
1dd10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ers..**.** ^The
1dd20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 sqlite3_vsnprint
1dd30 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 f() routine is a
1dd40 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e varargs version
1dd50 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1dd60 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 intf()..**.** Th
1dd70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
1dd80 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
1dd90 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
1dda0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
1ddb0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
1ddc0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
1ddd0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
1dde0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
1ddf0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
1de00 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1de10 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
1de20 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
1de30 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
1de40 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 ", and "%z" opti
1de50 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ons..**.** ^(The
1de60 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 %q option works
1de70 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 like %s in that
1de80 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 it substitutes
1de90 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 a nul-terminated
1dea0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 .** string from
1deb0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 the argument lis
1dec0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 t. But %q also
1ded0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c doubles every '\
1dee0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a '' character..**
1def0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 %q is designed
1df00 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 for use inside a
1df10 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1df20 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 )^ By doubling
1df30 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 each '\''.** cha
1df40 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 racter it escape
1df50 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 s that character
1df60 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 and allows it t
1df70 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e o be inserted in
1df80 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 to.** the string
1df90 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d ..**.** For exam
1dfa0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 ple, assume the
1dfb0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 string variable
1dfc0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 zText contains t
1dfd0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ext as follows:.
1dfe0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1dff0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1e000 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 *zText = "It's
1e010 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a a happy day!";.*
1e020 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e030 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 uote>.**.** One
1e040 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 can use this tex
1e050 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 t in an SQL stat
1e060 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 ement as follows
1e070 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1e080 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
1e090 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
1e0a0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
1e0b0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
1e0c0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 LUES('%q')", zTe
1e0d0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1e0e0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1e0f0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1e100 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1e110 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1e120 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 ckquote>.**.** B
1e130 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f ecause the %q fo
1e140 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 rmat string is u
1e150 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 sed, the '\'' ch
1e160 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 aracter in zText
1e170 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 .** is escaped a
1e180 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 nd the SQL gener
1e190 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f ated is as follo
1e1a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1e1b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e1c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e1d0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 e1 VALUES('It''s
1e1e0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a a happy day!').
1e1f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1e200 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1e210 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 s is correct. H
1e220 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e ad we used %s in
1e230 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 stead of %q, the
1e240 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a generated SQL.*
1e250 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f * would have loo
1e260 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a ked like this:.*
1e270 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1e280 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
1e290 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
1e2a0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 LUES('It's a hap
1e2b0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f py day!');.** </
1e2c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1e2d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 >.**.** This sec
1e2e0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 ond example is a
1e2f0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 n SQL syntax err
1e300 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 or. As a genera
1e310 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c l rule you shoul
1e320 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 d.** always use
1e330 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 %q instead of %s
1e340 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
1e350 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 text into a stri
1e360 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a ng literal..**.*
1e370 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f * ^(The %Q optio
1e380 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 n works like %q
1e390 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 except it also a
1e3a0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 dds single quote
1e3b0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 s around.** the
1e3c0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 outside of the t
1e3d0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 otal string. Ad
1e3e0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 ditionally, if t
1e3f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 he parameter in
1e400 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 the.** argument
1e410 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 list is a NULL p
1e420 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 ointer, %Q subst
1e430 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 itutes the text
1e440 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a "NULL" (without.
1e450 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ** single quotes
1e460 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ).)^ So, for ex
1e470 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
1e480 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
1e490 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1e4a0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1e4b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1e4c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e4d0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
1e4e0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
1e4f0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
1e500 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
1e510 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
1e520 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
1e530 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e540 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
1e550 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
1e560 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
1e570 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
1e580 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
1e590 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
1e5a0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
1e5b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1e5c0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 ^(The "%z" forma
1e5d0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
1e5e0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 ks like "%s" but
1e5f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 with the.** add
1e600 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 ition that after
1e610 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 the string has
1e620 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f been read and co
1e630 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 pied into.** the
1e640 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 result, [sqlite
1e650 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 3_free()] is cal
1e660 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 led on the input
1e670 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 string.)^.*/.SQ
1e680 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
1e690 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
1e6a0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
1e6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1e6c0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e *sqlite3_vmprin
1e6d0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 tf(const char*,
1e6e0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 va_list);.SQLITE
1e6f0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
1e700 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c e3_snprintf(int,
1e710 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1e720 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f *, ...);.SQLITE_
1e730 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
1e740 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 3_vsnprintf(int,
1e750 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1e760 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a *, va_list);../*
1e770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1e780 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
1e790 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 Subsystem.**.**
1e7a0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
1e7b0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
1e7c0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
1e7d0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
1e7e0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
1e7f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
1e800 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
1e810 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
1e820 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
1e830 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
1e840 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
1e850 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
1e860 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
1e870 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
1e880 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
1e890 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
1e8a0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
1e8b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1e8c0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
1e8d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1e8e0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
1e8f0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
1e900 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
1e910 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
1e920 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
1e930 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1e940 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
1e950 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
1e960 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
1e970 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
1e980 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
1e990 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 r. ^If the para
1e9a0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
1e9b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
1e9c0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
1e9d0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
1e9e0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
1e9f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
1ea00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 er..**.** ^Calli
1ea10 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
1ea20 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
1ea30 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
1ea40 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
1ea50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
1ea60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1ea70 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
1ea80 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
1ea90 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
1eaa0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 sed. ^The sqlit
1eab0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
1eac0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
1ead0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
1eae0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1eaf0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
1eb00 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
1eb10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1eb20 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
1eb30 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
1eb40 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
1eb50 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
1eb60 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
1eb70 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
1eb80 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
1eb90 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
1eba0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
1ebb0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
1ebc0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1ebd0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
1ebe0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
1ebf0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
1ec00 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1ec10 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
1ec20 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
1ec30 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
1ec40 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
1ec50 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
1ec60 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
1ec70 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1ec80 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1ec90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
1eca0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
1ecb0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 3_realloc() inte
1ecc0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
1ecd0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
1ece0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
1ecf0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c ation to be at l
1ed00 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 east N bytes, wh
1ed10 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
1ed20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1ed30 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c . The memory al
1ed40 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 location to be r
1ed50 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 esized is the fi
1ed60 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
1ed70 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 .)^ ^ If the fir
1ed80 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
1ed90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1eda0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 ).** is a NULL p
1edb0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 ointer then its
1edc0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e behavior is iden
1edd0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 tical to calling
1ede0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1edf0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 oc(N) where N is
1ee00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1ee10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1ee20 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e _realloc()..** ^
1ee30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
1ee40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1ee50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 e3_realloc() is
1ee60 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
1ee70 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
1ee80 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
1ee90 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
1eea0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
1eeb0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 free(P) where P
1eec0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
1eed0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1eee0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
1eef0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1ef00 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
1ef10 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
1ef20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
1ef30 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
1ef40 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 es in size or NU
1ef50 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 LL if sufficient
1ef60 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 memory is unava
1ef70 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d ilable..** ^If M
1ef80 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
1ef90 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1efa0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
1efb0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
1efc0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1efd0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
1efe0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
1eff0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
1f000 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
1f010 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e te3_realloc() an
1f020 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
1f030 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
1f040 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1f050 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
1f060 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 s NULL, then the
1f070 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f080 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 n.** is not free
1f090 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 d..**.** ^The me
1f0a0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 mory returned by
1f0b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f0c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
1f0d0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c alloc().** is al
1f0e0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 ways aligned to
1f0f0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 at least an 8 by
1f100 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 te boundary, or
1f110 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 to a.** 4 byte b
1f120 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b oundary if the [
1f130 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c SQLITE_4_BYTE_AL
1f140 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f IGNED_MALLOC] co
1f150 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
1f160 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a tion is used..**
1f170 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 .** In SQLite ve
1f180 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 rsion 3.5.0 and
1f190 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 3.5.1, it was po
1f1a0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 ssible to define
1f1b0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f .** the SQLITE_O
1f1c0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 MIT_MEMORY_ALLOC
1f1d0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c ATION which woul
1f1e0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c d cause the buil
1f1f0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e t-in.** implemen
1f200 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 tation of these
1f210 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f routines to be o
1f220 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 mitted. That ca
1f230 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e pability.** is n
1f240 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 o longer provide
1f250 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 d. Only built-i
1f260 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
1f270 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e ors can be used.
1f280 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 .**.** Prior to
1f290 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1f2a0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f .7.10, the Windo
1f2b0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 ws OS interface
1f2c0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 layer called.**
1f2d0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
1f2e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 c() and free() d
1f2f0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e irectly when con
1f300 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e verting.** filen
1f310 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 ames between the
1f320 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
1f330 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a used by SQLite.*
1f340 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 * and whatever f
1f350 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 ilename encoding
1f360 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
1f370 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f particular Windo
1f380 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 ws.** installati
1f390 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f on. Memory allo
1f3a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 cation errors we
1f3b0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 re detected, but
1f3c0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 .** they were re
1f3d0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
1f3e0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
1f3f0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
1f400 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
1f410 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
1f420 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ..**.** The poin
1f430 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
1f440 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1f450 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
1f460 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 ealloc()].** mus
1f470 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c t be either NULL
1f480 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 or else pointer
1f490 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
1f4a0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 a prior.** invoc
1f4b0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
1f4c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
1f4d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1f4e0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
1f4f0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c not yet been rel
1f500 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
1f510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
1f520 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 t not read or wr
1f530 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a ite any part of.
1f540 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 ** a block of me
1f550 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 mory after it ha
1f560 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 s been released
1f570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
1f580 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 3_free()] or [sq
1f590 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1f5a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1f5b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
1f5c0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
1f5d0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
1f5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 te3_realloc(void
1f5f0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
1f600 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
1f610 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
1f620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
1f630 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
1f640 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a Statistics.**.**
1f650 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 SQLite provides
1f660 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 these two inter
1f670 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 faces for report
1f680 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 ing on the statu
1f690 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c s.** of the [sql
1f6a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
1f6b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1f6c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 , and [sqlite3_r
1f6d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 ealloc()].** rou
1f6e0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 tines, which for
1f6f0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d m the built-in m
1f700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1f710 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a subsystem..**.*
1f720 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1f730 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
1f740 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1f750 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
1f760 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 es.** of memory
1f770 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 currently outsta
1f780 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 nding (malloced
1f790 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a but not freed)..
1f7a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
1f7b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1f7c0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 r()] routine ret
1f7d0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d urns the maximum
1f7e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 .** value of [sq
1f7f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1f800 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
1f810 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1f820 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 * was last reset
1f830 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 . ^The values r
1f840 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1f850 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1f860 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1f870 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1f880 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 ter()] include a
1f890 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 ny overhead.** a
1f8a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 dded by SQLite i
1f8b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 n its implementa
1f8c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1f8d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 _malloc()],.** b
1f8e0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
1f8f0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
1f900 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
1f910 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f em library.** ro
1f920 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c utines that [sql
1f930 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d ite3_malloc()] m
1f940 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e ay call..**.** ^
1f950 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d The memory high-
1f960 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 water mark is re
1f970 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 set to the curre
1f980 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b nt value of.** [
1f990 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1f9a0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
1f9b0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
1f9c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
1f9d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1f9e0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 ter()] is true.
1f9f0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 ^The value retu
1fa00 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
1fa10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1fa20 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 ater(1)] is the
1fa30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a high-water mark.
1fa40 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ** prior to the
1fa50 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 reset..*/.SQLITE
1fa60 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
1fa70 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
1fa80 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 y_used(void);.SQ
1fa90 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
1faa0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
1fab0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1fac0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a int resetFlag);.
1fad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1fae0 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e Pseudo-Random N
1faf0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a umber Generator.
1fb00 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e **.** SQLite con
1fb10 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 tains a high-qua
1fb20 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 lity pseudo-rand
1fb30 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 om number genera
1fb40 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 tor (PRNG) used
1fb50 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e to.** select ran
1fb60 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 dom [ROWID | ROW
1fb70 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 IDs] when insert
1fb80 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 ing new records
1fb90 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 into a table tha
1fba0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 t.** already use
1fbb0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f s the largest po
1fbc0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 ssible [ROWID].
1fbd0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 The PRNG is als
1fbe0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 o used for.** th
1fbf0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f e build-in rando
1fc00 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c m() and randombl
1fc10 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f ob() SQL functio
1fc20 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 ns. This interf
1fc30 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 ace allows.** ap
1fc40 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 plications to ac
1fc50 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 cess the same PR
1fc60 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 NG for other pur
1fc70 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 poses..**.** ^A
1fc80 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 call to this rou
1fc90 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 tine stores N by
1fca0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
1fcb0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e s into buffer P.
1fcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
1fcd0 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 t time this rout
1fce0 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 ine is invoked (
1fcf0 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c either internall
1fd00 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 y or by.** the a
1fd10 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 pplication) the
1fd20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 PRNG is seeded u
1fd30 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 sing randomness
1fd40 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
1fd50 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 the xRandomness
1fd60 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 method of the d
1fd70 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
1fd80 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 vfs] object..**
1fd90 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 ^On all subseque
1fda0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 nt invocations,
1fdb0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f the pseudo-rando
1fdc0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 mness is generat
1fdd0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 ed.** internally
1fde0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 and without rec
1fdf0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 ourse to the [sq
1fe00 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 lite3_vfs] xRand
1fe10 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 omness.** method
1fe20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
1fe30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e void sqlite3_ran
1fe40 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 domness(int N, v
1fe50 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid *P);../*.**
1fe60 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
1fe70 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 e-Time Authoriza
1fe80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
1fe90 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
1fea0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 ne registers an
1feb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1fec0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
1fed0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1fee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
1fef0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
1ff00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
1ff10 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
1ff20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1ff30 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
1ff40 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
1ff50 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
1ff60 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
1ff70 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
1ff80 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
1ff90 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
1ffa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1ffb0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
1ffc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1ffd0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 ()]. ^At variou
1ffe0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 s.** points duri
1fff0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 ng the compilati
20000 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c on process, as l
20010 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 ogic is being cr
20020 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 eated.** to perf
20030 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 orm various acti
20040 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 ons, the authori
20050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
20060 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 invoked to.** se
20070 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f e if those actio
20080 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 ns are allowed.
20090 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
200a0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
200b0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
200c0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 TE_OK] to allow
200d0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c the action, [SQL
200e0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 ITE_IGNORE] to d
200f0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 isallow the.** s
20100 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 pecific action b
20110 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c ut allow the SQL
20120 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f statement to co
20130 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 ntinue to be.**
20140 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 compiled, or [SQ
20150 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 LITE_DENY] to ca
20160 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 use the entire S
20170 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
20180 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 be.** rejected w
20190 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
201a0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 If the authorize
201b0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 r callback retur
201c0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 ns.** any value
201d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
201e0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c TE_IGNORE], [SQL
201f0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c ITE_OK], or [SQL
20200 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 ITE_DENY].** the
20210 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 n the [sqlite3_p
20220 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
20230 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
20240 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a that triggered.*
20250 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
20260 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
20270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
20280 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
20290 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
202a0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
202b0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 hat means the op
202c0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 eration.** reque
202d0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 sted is ok. ^Wh
202e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
202f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
20300 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 DENY], the.** [s
20310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20320 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
20330 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
20340 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 ggered the.** au
20350 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
20360 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
20370 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e message explain
20380 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 ing that.** acce
20390 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a ss is denied. .*
203a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
203b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
203c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
203d0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f back is a copy o
203e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
203f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
20400 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
20410 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 orizer() interfa
20420 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ce. ^The second
20430 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
20440 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
20450 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 an integer [SQLI
20460 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e TE_COPY | action
20470 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
20480 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 ifies.** the par
20490 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 ticular action t
204a0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e o be authorized.
204b0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f ^The third thro
204c0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
204d0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ters.** to the c
204e0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f allback are zero
204f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
20500 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e ngs that contain
20510 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 additional.** d
20520 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 etails about the
20530 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
20540 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 thorized..**.**
20550 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 ^If the action c
20560 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 ode is [SQLITE_R
20570 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 EAD].** and the
20580 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
20590 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
205a0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 then the.** [pr
205b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
205c0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 ] statement is c
205d0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 onstructed to su
205e0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 bstitute.** a NU
205f0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
20600 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
20610 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
20620 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 have.** been re
20630 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b ad if [SQLITE_OK
20640 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 ] had been retur
20650 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ned. The [SQLIT
20660 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 E_IGNORE].** ret
20670 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 urn can be used
20680 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 to deny an untru
20690 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 sted user access
206a0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a to individual.*
206b0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 * columns of a t
206c0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 able..** ^If the
206d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
206e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
206f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
20700 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
20710 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
20720 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
20730 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
20740 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
20750 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
20760 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
20770 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
20780 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
20790 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
207a0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
207b0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
207c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
207d0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
207e0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
207f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
20800 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
20810 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
20820 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
20830 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
20840 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
20850 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
20860 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
20870 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
20880 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
20890 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
208a0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
208b0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
208c0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
208d0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
208e0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
208f0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
20900 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
20910 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
20920 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
20930 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
20940 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
20950 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
20960 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
20970 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
20980 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
20990 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
209a0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
209b0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
209c0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
209d0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
209e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
209f0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
20a00 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
20a10 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
20a20 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
20a30 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
20a40 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
20a50 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
20a60 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
20a70 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
20a80 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
20a90 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
20aa0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
20ab0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
20ac0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
20ad0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
20ae0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
20af0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
20b00 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
20b10 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
20b20 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
20b30 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
20b40 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
20b50 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
20b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20b70 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
20b80 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
20b90 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
20ba0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
20bb0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
20bc0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
20bd0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
20be0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
20bf0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
20c00 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
20c10 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
20c20 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
20c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20c40 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
20c50 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
20c60 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
20c70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
20c80 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
20c90 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
20ca0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
20cb0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
20cc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
20cd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
20ce0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
20cf0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
20d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
20d10 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
20d20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
20d30 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
20d40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
20d50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20d60 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
20d70 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
20d80 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
20d90 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
20da0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
20db0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
20dc0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
20dd0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
20de0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
20df0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
20e00 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
20e10 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
20e20 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
20e30 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
20e40 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
20e50 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
20e60 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
20e70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20e80 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
20e90 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
20ea0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
20eb0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
20ec0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
20ed0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
20ee0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
20ef0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
20f00 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
20f10 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
20f20 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
20f30 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
20f40 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
20f50 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
20f60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
20f70 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
20f80 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
20f90 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
20fa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
20fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f int sqlite3_set_
20fc0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 authorizer(. sq
20fd0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a lite3*,. int (*
20fe0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 xAuth)(void*,int
20ff0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
21000 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
21010 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
21020 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 ),. void *pUser
21030 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Data.);../*.** C
21040 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
21050 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 zer Return Codes
21060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
21070 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
21080 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
21090 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
210a0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
210b0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
210c0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
210d0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
210e0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
210f0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
21100 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
21110 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
21120 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
21130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
21140 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
21150 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
21160 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
21170 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
21180 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 ation..**.** Not
21190 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 e that SQLITE_IG
211a0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 NORE is also use
211b0 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 d as a [SQLITE_R
211c0 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e OLLBACK | return
211d0 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 code].** from t
211e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 he [sqlite3_vtab
211f0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 _on_conflict()]
21200 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 interface..*/.#d
21210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e efine SQLITE_DEN
21220 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 Y 1 /* Abort
21230 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
21240 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 nt with an error
21250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21260 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a TE_IGNORE 2 /*
21270 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 Don't allow acc
21280 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 ess, but don't g
21290 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 enerate an error
212a0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
212b0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
212c0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a Action Codes.**.
212d0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
212e0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
212f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
21300 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
21310 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 function.** tha
21320 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 t is invoked to
21330 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 authorize certai
21340 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
21350 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a actions. The.**
21360 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
21370 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 r to the callbac
21380 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
21390 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 code that specif
213a0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 ies.** what acti
213b0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 on is being auth
213c0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 orized. These a
213d0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 re the integer a
213e0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 ction codes that
213f0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
21400 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 er callback may
21410 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a be passed..**.**
21420 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f These action co
21430 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 de values signif
21440 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f y what kind of o
21450 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 peration is to b
21460 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e e.** authorized.
21470 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 The 3rd and 4t
21480 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
21490 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f the authorizatio
214a0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 n.** callback fu
214b0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 nction will be p
214c0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c arameters or NUL
214d0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 L depending on w
214e0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a hich of these.**
214f0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 codes is used a
21500 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
21510 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 ameter. ^(The 5
21520 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
21530 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
21540 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
21550 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
21560 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 tabase ("main",
21570 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 "temp",.** etc.)
21580 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 if applicable.)
21590 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 ^ ^The 6th para
215a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 meter to the aut
215b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
215c0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
215d0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 of the inner-mos
215e0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 t trigger or vie
215f0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e w that is respon
21600 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 sible for.** the
21610 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
21620 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 or NULL if this
21630 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 access attempt i
21640 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a s directly from.
21650 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c ** top-level SQL
21660 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
21670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21690 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
216a0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
216b0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
216c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
216d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
216e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
216f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
21700 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21710 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
21720 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
21730 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
21740 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
21750 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21760 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
21770 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
21780 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
21790 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
217a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
217b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
217c0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
217d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
217e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
217f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21800 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
21810 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
21820 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
21830 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
21840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21850 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
21860 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
21870 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
21880 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
21890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
218a0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
218b0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
218c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
218d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
218e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
218f0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
21900 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
21910 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
21920 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21940 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
21950 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
21960 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
21970 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
21980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
21990 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
219a0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
219b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
219c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
219d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
219e0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
219f0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
21a00 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
21a10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
21a30 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
21a40 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
21a50 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
21a60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
21a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
21a80 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
21a90 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
21aa0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
21ab0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
21ac0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
21ad0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
21ae0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
21af0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
21b00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
21b10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
21b20 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
21b30 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
21b40 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
21b50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
21b60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
21b70 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
21b80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
21b90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
21ba0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21bb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
21bc0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
21bd0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
21be0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21bf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21c00 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
21c10 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
21c20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
21c30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
21c40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21c50 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
21c60 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
21c70 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
21c80 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
21c90 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
21ca0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
21cb0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
21cc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
21cd0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
21ce0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21cf0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
21d00 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
21d10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21d20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21d40 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
21d50 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
21d60 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
21d70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
21d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21d90 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
21da0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
21db0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
21dc0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
21dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21de0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
21df0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
21e00 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
21e10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21e30 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
21e40 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
21e50 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
21e60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
21e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
21e80 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
21e90 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
21ea0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
21eb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
21ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
21ed0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
21ee0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
21ef0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
21f00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
21f20 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
21f30 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
21f40 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
21f50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
21f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
21f70 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
21f80 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
21f90 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
21fa0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
21fb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
21fc0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
21fd0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
21fe0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
21ff0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
22000 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
22010 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
22020 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
22030 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 Function
22040 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
22050 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 e SQLITE_SAVEPOI
22060 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 NT 32
22070 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
22080 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 Savepoint
22090 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 Name */.#define
220a0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
220b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
220c0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
220d0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
220e0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
220f0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
22100 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
22110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
22120 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
22130 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
22140 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
22150 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
22160 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
22170 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
22180 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
22190 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
221a0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
221b0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
221c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
221d0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
221e0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
221f0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
22200 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
22210 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
22220 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
22230 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
22240 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
22250 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
22260 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
22270 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
22280 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
22290 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
222a0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
222b0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
222c0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
222d0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
222e0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
222f0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
22300 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
22310 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
22320 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
22330 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
22340 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
22350 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
22360 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
22370 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
22380 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
22390 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
223a0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
223b0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
223c0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 finishes. ^The
223d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
223e0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
223f0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
22400 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 ent text and an
22410 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c estimate of wall
22420 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f -clock time.** o
22430 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 f how long that
22440 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 statement took t
22450 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f o run. ^The pro
22460 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a file callback.**
22470 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 time is in unit
22480 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 s of nanoseconds
22490 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 , however the cu
224a0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 rrent implementa
224b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 tion.** is only
224c0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 capable of milli
224d0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f second resolutio
224e0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 n so the six lea
224f0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a st significant.*
22500 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 * digits in the
22510 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 time are meaning
22520 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 less. Future ve
22530 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
22540 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 .** might provid
22550 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 e greater resolu
22560 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 tion on the prof
22570 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 iler callback.
22580 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 The.** sqlite3_p
22590 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f rofile() functio
225a0 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 n is considered
225b0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 experimental and
225c0 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 is.** subject t
225d0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 o change in futu
225e0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
225f0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 QLite..*/.SQLITE
22600 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
22610 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
22620 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
22630 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
22640 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
22650 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 ITE_API SQLITE_E
22660 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
22670 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c *sqlite3_profil
22680 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 e(sqlite3*,. v
22690 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 oid(*xProfile)(v
226a0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
226b0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 ,sqlite3_uint64)
226c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
226d0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
226e0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 Progress Callba
226f0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 cks.**.** ^The s
22700 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
22710 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 handler(D,N,X,P)
22720 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
22730 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a s the callback.*
22740 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 * function X to
22750 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f be invoked perio
22760 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c dically during l
22770 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c ong running call
22780 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
22790 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 _exec()], [sqlit
227a0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b e3_step()] and [
227b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
227c0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 e()] for.** data
227d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
227e0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 D. An example u
227f0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 se for this.** i
22800 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b nterface is to k
22810 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 eep a GUI update
22820 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 d during a large
22830 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 query..**.** ^T
22840 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 he parameter P i
22850 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
22860 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 as the only par
22870 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a ameter to the .*
22880 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
22890 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 ion X. ^The par
228a0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 ameter N is the
228b0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
228c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
228d0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
228e0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
228f0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
22900 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
22910 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
22920 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 k X..**.** ^Only
22930 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 a single progre
22940 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 ss handler may b
22950 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 e defined at one
22960 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 time per.** [da
22970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
22980 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 n]; setting a ne
22990 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c w progress handl
229a0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a er cancels the.*
229b0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 * old one. ^Set
229c0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 ting parameter X
229d0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 to NULL disable
229e0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 s the progress h
229f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 andler..** ^The
22a00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
22a10 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 is also disable
22a20 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 d by setting N t
22a30 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a o a value less.*
22a40 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 * than 1..**.**
22a50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 ^If the progress
22a60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
22a70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
22a80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 operation is.**
22a90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 interrupted. Th
22aa0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 is feature can b
22ab0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d e used to implem
22ac0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c ent a.** "Cancel
22ad0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 " button on a GU
22ae0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f I progress dialo
22af0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 g box..**.** The
22b00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
22b10 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 r callback must
22b20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
22b30 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
22b40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
22b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
22b60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f invoked the pro
22b70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
22b80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
22b90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
22ba0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
22bb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
22bc0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
22bd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22be0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
22bf0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
22c00 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
22c10 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .**.*/.SQLITE_AP
22c20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 I void sqlite3_p
22c30 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
22c40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
22c50 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
22c60 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
22c70 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
22c80 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
22c90 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e nnection.**.** ^
22ca0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
22cb0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
22cc0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
22cd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
22ce0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
22cf0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
22d00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
22d10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
22d20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
22d30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
22d40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
22d50 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
22d60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
22d70 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
22d80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
22d90 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
22da0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
22db0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
22dc0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
22dd0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
22de0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
22df0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
22e00 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
22e10 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
22e20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
22e30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
22e40 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
22e50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
22e60 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
22e70 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
22e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
22e90 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
22ea0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
22eb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
22ec0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
22ed0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
22ee0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
22ef0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
22f00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
22f10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
22f20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
22f30 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
22f40 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
22f50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
22f60 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
22f70 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
22f80 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
22f90 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
22fa0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
22fb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
22fc0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
22fd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
22fe0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
22ff0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
23000 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 t encoding for t
23010 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c he database will
23020 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 be UTF-8 if.**
23030 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
23040 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
23050 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 2() is called an
23060 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 d.** UTF-16 in t
23070 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
23080 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f rder if sqlite3_
23090 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 open16() is used
230a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 ..**.** Whether
230b0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 or not an error
230c0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 occurs when it i
230d0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 s opened, resour
230e0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ces.** associate
230f0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
23100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
23110 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 handle should b
23120 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a e released by.**
23130 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
23140 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
23150 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c when it is no l
23160 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a onger required..
23170 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
23180 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 3_open_v2() inte
23190 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
231a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a sqlite3_open().
231b0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ** except that i
231c0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 t accepts two ad
231d0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 ditional paramet
231e0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ers for addition
231f0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 al control.** ov
23200 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 er the new datab
23210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
23220 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 ^(The flags par
23230 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c ameter to.** sql
23240 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 ite3_open_v2() c
23250 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
23260 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
23270 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
23280 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
23290 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
232a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
232b0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 TEX], [SQLITE_OP
232c0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b EN_FULLMUTEX], [
232d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
232e0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 EDCACHE],.** [SQ
232f0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
23300 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 ECACHE], and/or
23310 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
23320 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a ] flags:)^.**.**
23330 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b <dl>.** ^(<dt>[
23340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
23350 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ONLY]</dt>.** <d
23360 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
23370 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 s opened in read
23380 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 -only mode. If
23390 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
233a0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 s not.** already
233b0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 exist, an error
233c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
233d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
233e0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
233f0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a ADWRITE]</dt>.**
23400 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
23410 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
23420 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
23430 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c ing if possible,
23440 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f or reading.** o
23450 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 nly if the file
23460 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 is write protect
23470 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 ed by the operat
23480 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 ing system. In
23490 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 either.** case t
234a0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 he database must
234b0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
234c0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 otherwise an err
234d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
234e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
234f0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
23500 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
23510 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
23520 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
23530 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
23540 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 ened for reading
23550 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e and writing, an
23560 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a d is created if.
23570 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 ** it does not a
23580 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 lready exist. Th
23590 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 is is the behavi
235a0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 or that is alway
235b0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 s used for.** sq
235c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 lite3_open() and
235d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
235e0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 ).</dd>)^.** </d
235f0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 l>.**.** If the
23600 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
23610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
23620 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
23630 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 the.** combinat
23640 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 ions shown above
23650 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 optionally comb
23660 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a ined with other.
23670 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
23680 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 READONLY | SQLIT
23690 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a E_OPEN_* bits].*
236a0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 * then the behav
236b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
236c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
236d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
236e0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
236f0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 t, then the data
23700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
23710 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 ** opens in the
23720 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 multi-thread [th
23730 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 reading mode] as
23740 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e long as the sin
23750 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f gle-thread.** mo
23760 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 de has not been
23770 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 set at compile-t
23780 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
23790 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b e. ^If the.** [
237a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c SQLITE_OPEN_FULL
237b0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
237c0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 et then the data
237d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
237e0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 opens.** in the
237f0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
23800 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 ading mode] unle
23810 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 ss single-thread
23820 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 was.** previous
23830 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 ly selected at c
23840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
23850 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 tart-time..** ^T
23860 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
23870 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 SHAREDCACHE] fla
23880 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
23890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
238a0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 to be.** eligib
238b0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 le to use [share
238c0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 d cache mode], r
238d0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
238e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
238f0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 ed.** cache is e
23900 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
23910 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
23920 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e red_cache()]. ^
23930 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f The.** [SQLITE_O
23940 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
23950 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 ] flag causes th
23960 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
23970 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 ction to not.**
23980 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b participate in [
23990 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
239a0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 e] even if it is
239b0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
239c0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
239d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
239e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 _open_v2() is th
239f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
23a00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
23a10 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e bject that defin
23a20 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
23a30 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
23a40 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 e that.** the ne
23a50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 w database conne
23a60 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 ction should use
23a70 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 . ^If the fourt
23a80 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
23a90 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
23aa0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c then the defaul
23ab0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
23ac0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a object is used..
23ad0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
23ae0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f lename is ":memo
23af0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 ry:", then a pri
23b00 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 vate, temporary
23b10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
23b20 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 se.** is created
23b30 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
23b40 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d ion. ^This in-m
23b50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
23b60 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
23b70 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
23b80 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
23b90 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
23ba0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
23bb0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
23bc0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
23bd0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
23be0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
23bf0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
23c00 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
23c10 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
23c20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
23c30 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
23c40 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
23c50 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
23c60 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
23c70 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
23c80 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
23c90 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
23ca0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
23cb0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iguity..**.** ^I
23cc0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
23cd0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
23ce0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
23cf0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 e, temporary.**
23d00 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 on-disk database
23d10 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 will be created
23d20 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 . ^This private
23d30 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
23d40 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
23d50 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
23d60 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
23d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
23d80 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b closed..**.** [
23d90 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 [URI filenames i
23da0 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 n sqlite3_open()
23db0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e ]] <h3>URI Filen
23dc0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ames</h3>.**.**
23dd0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d ^If [URI filenam
23de0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f e] interpretatio
23df0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e n is enabled, an
23e00 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 d the filename a
23e10 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e rgument.** begin
23e20 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 s with "file:",
23e30 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d then the filenam
23e40 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 e is interpreted
23e50 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a as a URI. ^URI.
23e60 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 ** filename inte
23e70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e rpretation is en
23e80 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 abled if the [SQ
23e90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
23ea0 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e lag is.** set in
23eb0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
23ec0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
23ed0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 open_v2(), or if
23ee0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 it has.** been
23ef0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 enabled globally
23f00 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
23f10 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f TE_CONFIG_URI] o
23f20 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a ption with the.*
23f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
23f40 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 g()] method or b
23f50 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 y the [SQLITE_US
23f60 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 E_URI] compile-t
23f70 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 ime option..** A
23f80 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 s of SQLite vers
23f90 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 ion 3.7.7, URI f
23fa0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
23fb0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 tation is turned
23fc0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 off.** by defau
23fd0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 lt, but future r
23fe0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
23ff0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 e might enable U
24000 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 RI filename.** i
24010 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 nterpretation by
24020 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 default. See "
24030 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 [URI filenames]"
24040 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
24050 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
24060 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 **.** URI filena
24070 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 mes are parsed a
24080 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 ccording to RFC
24090 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 3986. ^If the UR
240a0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a I contains an.**
240b0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e authority, then
240c0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 it must be eith
240d0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 er an empty stri
240e0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 ng or the string
240f0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 .** "localhost"
24100 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 . ^If the author
24110 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d ity is not an em
24120 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c pty string or "l
24130 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a ocalhost", an .*
24140 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 * error is retur
24150 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 ned to the calle
24160 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 r. ^The fragment
24170 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
24180 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 URI, if .** pres
24190 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e ent, is ignored.
241a0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 .**.** ^SQLite u
241b0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d ses the path com
241c0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 ponent of the UR
241d0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 I as the name of
241e0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a the disk file.*
241f0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 * which contains
24200 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e the database. ^
24210 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 If the path begi
24220 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 ns with a '/' ch
24230 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 aracter, .** the
24240 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 n it is interpre
24250 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 ted as an absolu
24260 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 te path. ^If the
24270 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 path does not b
24280 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 egin .** with a
24290 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 '/' (meaning tha
242a0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 t the authority
242b0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 section is omitt
242c0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 ed from the URI)
242d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 .** then the pat
242e0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
242f0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 as a relative p
24300 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e ath. .** ^On win
24310 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
24320 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
24330 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
24340 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
24350 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
24360 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b "C:")..**.** [[
24370 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 core URI query p
24380 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 arameters]].** T
24390 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 he query compone
243a0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 nt of a URI may
243b0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 contain paramete
243c0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 rs that are inte
243d0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 rpreted.** eithe
243e0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 r by SQLite itse
243f0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 lf, or by a [VFS
24400 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d | custom VFS im
24410 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a plementation]..*
24420 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 * SQLite interpr
24430 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ets the followin
24440 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61 g three query pa
24450 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 rameters:.**.**
24460 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c <ul>.** <li> <
24470 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 b>vfs</b>: ^The
24480 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 "vfs" parameter
24490 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 may be used to s
244a0 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 pecify the name
244b0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 of.** a VFS
244c0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 object that prov
244d0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ides the operati
244e0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
244f0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a ace that should.
24500 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 ** be used t
24510 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 o access the dat
24520 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 abase file on di
24530 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 sk. ^If this opt
24540 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a ion is set to.**
24550 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 an empty st
24560 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 ring the default
24570 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 VFS object is u
24580 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 sed. ^Specifying
24590 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 an unknown.**
245a0 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 VFS is an err
245b0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f or. ^If sqlite3_
245c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
245d0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 d and the vfs op
245e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 tion is.** p
245f0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 resent, then the
24600 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 VFS specified b
24610 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b y the option tak
24620 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 es precedence ov
24630 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 er.** the va
24640 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
24650 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
24660 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
24670 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 en_v2()..**.**
24680 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 <li> <b>mode</b
24690 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 >: ^(The mode pa
246a0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
246b0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f et to either "ro
246c0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 ", "rw",.**
246d0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 "rwc", or "memor
246e0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 y". Attempting t
246f0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 o set it to any
24700 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a other value is.*
24710 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e * an error)^
24720 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 . .** ^If "r
24730 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c o" is specified,
24740 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
24750 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
24760 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 read-only .**
24770 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 access, just
24780 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 as if the [SQLIT
24790 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
247a0 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 flag had been s
247b0 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 et in the .**
247c0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 third argument
247d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
247e0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d _v2(). ^If the m
247f0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ode option is se
24800 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 t to .** "rw
24810 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 ", then the data
24820 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
24830 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 or read-write (b
24840 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a ut not create) .
24850 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 ** access, a
24860 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e s if SQLITE_OPEN
24870 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 _READWRITE (but
24880 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f not SQLITE_OPEN_
24890 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 CREATE) had .**
248a0 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 been set. ^V
248b0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 alue "rwc" is eq
248c0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
248d0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 ing both .**
248e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
248f0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 DWRITE and SQLIT
24900 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 E_OPEN_CREATE.
24910 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
24920 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 ion is.** se
24930 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 t to "memory" th
24940 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 en a pure [in-me
24950 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 mory database] t
24960 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a hat never reads.
24970 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 ** or writes
24980 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 from disk is us
24990 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 ed. ^It is an er
249a0 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 ror to specify a
249b0 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 value for.**
249c0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d the mode param
249d0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 eter that is les
249e0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 s restrictive th
249f0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 an that specifie
24a00 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 d by.** the
24a10 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 flags passed in
24a20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
24a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
24a40 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
24a50 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c <li> <b>cache<
24a60 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 /b>: ^The cache
24a70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
24a80 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
24a90 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 shared" or.**
24aa0 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 "private". ^Se
24ab0 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 tting it to "sha
24ac0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 red" is equivale
24ad0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 nt to setting th
24ae0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f e.** SQLITE_
24af0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
24b00 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 bit in the flag
24b10 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 s argument passe
24b20 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 d to.** sqli
24b30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
24b40 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 Setting the cach
24b50 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 e parameter to "
24b60 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 private" is .**
24b70 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 equivalent t
24b80 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 o setting the SQ
24b90 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
24ba0 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 ECACHE bit..**
24bb0 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f ^If sqlite3_o
24bc0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 pen_v2() is used
24bd0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 and the "cache"
24be0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
24bf0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 esent in.**
24c00 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 a URI filename,
24c10 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 its value overri
24c20 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 des any behaviou
24c30 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 r requested by s
24c40 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 etting.** SQ
24c50 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
24c60 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 ECACHE or SQLITE
24c70 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
24c80 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e E flag..** </ul>
24c90 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
24ca0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
24cb0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
24cc0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
24cd0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
24ce0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 n.** error. Fut
24cf0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
24d00 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 SQLite might und
24d10 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e erstand addition
24d20 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 al query.** para
24d30 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 meters. See "[q
24d40 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 uery parameters
24d50 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 with special mea
24d60 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 ning to SQLite]"
24d70 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
24d80 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
24d90 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
24da0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 name examples]]
24db0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 <h3>URI filename
24dc0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a examples</h3>.*
24dd0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
24de0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e er="1" align=cen
24df0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d ter cellpadding=
24e00 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 5>.** <tr><th> U
24e10 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 RI filenames <th
24e20 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 > Results.** <tr
24e30 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
24e40 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
24e50 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 Open the fi
24e60 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
24e70 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
24e80 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ctory..** <tr><t
24e90 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
24ea0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a ed/data.db<br>.*
24eb0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
24ec0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ///home/fred/dat
24ed0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 a.db <br> .**
24ee0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f file://lo
24ef0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 calhost/home/fre
24f00 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c d/data.db <br> <
24f10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
24f20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 Open the databa
24f30 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 se file "/home/f
24f40 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a red/data.db"..**
24f50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
24f60 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 /darkstar/home/f
24f70 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e red/data.db <td>
24f80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
24f90 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 error. "darksta
24fa0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f r" is not a reco
24fb0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 gnized authority
24fc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 ..** <tr><td sty
24fd0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a le="white-space:
24fe0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 nowrap"> .**
24ff0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a file:///C:
25000 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 /Documents%20and
25010 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 %20Settings/fred
25020 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 /Desktop/data.db
25030 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e .** <td> Win
25040 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 dows only: Open
25050 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
25060 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 b" on fred's des
25070 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a ktop on drive.**
25080 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f C:. No
25090 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 te that the %20
250a0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 escaping in this
250b0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 example is not
250c0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 strictly .**
250d0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 necessary
250e0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 - space characte
250f0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c rs can be used l
25100 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 iterally.**
25110 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 in URI file
25120 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 names..** <tr><t
25130 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
25140 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 mode=ro&cache=pr
25150 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 ivate <td> .**
25160 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c Open fil
25170 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
25180 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
25190 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e tory for read-on
251a0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 ly access..**
251b0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 Regardles
251c0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
251d0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 not shared-cache
251e0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
251f0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 by.**
25200 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 default, use a p
25210 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a rivate cache..**
25220 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
25230 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
25240 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 b?vfs=unix-noloc
25250 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 k <td>.**
25260 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 Open file "/h
25270 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
25280 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 ". Use the speci
25290 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c al VFS "unix-nol
252a0 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ock"..** <tr><td
252b0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
252c0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 ode=readonly <td
252d0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
252e0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e n error. "readon
252f0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c ly" is not a val
25300 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 id option for th
25310 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 e "mode" paramet
25320 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a er..** </table>.
25330 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 **.** ^URI hexad
25340 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
25350 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 quences (%HH) ar
25360 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 e supported with
25370 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a in the path and.
25380 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 ** query compone
25390 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 nts of a URI. A
253a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
253b0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 pe sequence cons
253c0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 ists of a.** per
253d0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 cent sign - "%"
253e0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 - followed by ex
253f0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 actly two hexade
25400 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a cimal digits .**
25410 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f specifying an o
25420 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 ctet value. ^Bef
25430 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 ore the path or
25440 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
25450 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c of a.** URI fil
25460 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 ename are interp
25470 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 reted, they are
25480 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 encoded using UT
25490 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 F-8 and all .**
254a0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
254b0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 pe sequences rep
254c0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c laced by a singl
254d0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e e byte containin
254e0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 g the.** corresp
254f0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 onding octet. If
25500 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 this process ge
25510 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c nerates an inval
25520 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e id UTF-8 encodin
25530 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 g,.** the result
25540 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
25550 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 .**.** <b>Note t
25560 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a o Windows users:
25570 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 </b> The encodi
25580 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 ng used for the
25590 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
255a0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f t.** of sqlite3_
255b0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
255c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 e3_open_v2() mus
255d0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 t be UTF-8, not
255e0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 whatever.** code
255f0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c page is currentl
25600 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 y defined. File
25610 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 names containing
25620 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a international.*
25630 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 * characters mus
25640 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 t be converted t
25650 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f o UTF-8 prior to
25660 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e passing them in
25670 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 to.** sqlite3_op
25680 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f en() or sqlite3_
25690 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
256a0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
256b0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 ows Runtime user
256c0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 s:</b> The temp
256d0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 orary directory
256e0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 must be set.** p
256f0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 rior to calling
25700 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
25710 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
25720 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 2(). Otherwise,
25730 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 various.** feat
25740 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 ures that requir
25750 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d e the use of tem
25760 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 porary files may
25770 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 fail..**.** See
25780 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
25790 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a temp_directory].
257a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
257b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
257c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
257d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
257e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
257f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
25800 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
25810 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
25820 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
25830 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
25840 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 t sqlite3_open16
25850 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a (. const void *
25860 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 filename, /* D
25870 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
25880 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 (UTF-16) */. s
25890 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 qlite3 **ppDb
258a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
258b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
258c0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
258d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 int sqlite3_ope
258e0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
258f0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
25900 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
25910 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
25920 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
25930 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
25940 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
25950 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
25960 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
25970 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
25980 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
25990 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
259a0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
259b0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
259c0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
259d0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
259e0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
259f0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
25a00 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
25a10 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
25a20 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
25a30 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
25a40 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
25a50 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
25a60 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
25a70 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
25a80 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
25a90 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
25aa0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
25ab0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25ac0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
25ad0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
25ae0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
25af0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
25b00 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
25b10 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
25b20 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
25b30 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
25b40 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
25b50 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
25b60 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
25b70 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
25b80 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
25b90 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
25ba0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
25bb0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
25bc0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
25bd0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
25be0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
25bf0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
25c00 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
25c10 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
25c20 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
25c30 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
25c40 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
25c50 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25c60 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
25c70 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
25c80 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
25c90 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
25ca0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
25cb0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
25cc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
25cd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
25ce0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
25cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
25d00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
25d10 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
25d20 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
25d30 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
25d40 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
25d50 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
25d60 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
25d70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
25d80 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
25d90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
25da0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
25db0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
25dc0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
25dd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
25de0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
25df0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
25e00 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
25e10 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
25e20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
25e30 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
25e40 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
25e50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
25e60 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
25e70 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
25e80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
25e90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25ea0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
25eb0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
25ec0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
25ed0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
25ee0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
25ef0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
25f00 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
25f10 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
25f20 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
25f30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
25f40 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
25f50 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
25f60 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
25f70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
25f80 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
25f90 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
25fa0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
25fb0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
25fc0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
25fd0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
25fe0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
25ff0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
26000 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
26010 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
26020 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
26030 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
26040 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
26050 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
26060 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
26070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
26080 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
26090 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
260a0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
260b0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
260c0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
260d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
260e0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
260f0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
26100 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
26110 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
26120 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
26130 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
26140 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
26150 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
26160 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
26170 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
26180 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
26190 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
261a0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
261b0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
261c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
261d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
261e0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 _uri_parameter(c
261f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
26200 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 name, const char
26210 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 *zParam);.SQLIT
26220 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
26230 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 3_uri_boolean(co
26240 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
26250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
26260 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c ram, int bDefaul
26270 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 t);.SQLITE_API s
26280 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
26290 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 ite3_uri_int64(c
262a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 onst char*, cons
262b0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 t char*, sqlite3
262c0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a _int64);.../*.**
262d0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 CAPI3REF: Error
262e0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 Codes And Messa
262f0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ges.**.** ^The s
26300 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
26310 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
26320 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b ns the numeric [
26330 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a result code] or.
26340 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
26350 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
26360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 e most recent fa
26370 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 iled sqlite3_* A
26380 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 PI call.** assoc
26390 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 iated with a [da
263a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
263b0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 n]. If a prior A
263c0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a PI call failed.*
263d0 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 * but the most r
263e0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 ecent API call s
263f0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 ucceeded, the re
26400 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a turn value from.
26410 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f ** sqlite3_errco
26420 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 de() is undefine
26430 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 d. ^The sqlite3
26440 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
26450 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
26460 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 is the same exc
26470 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 ept that it alwa
26480 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a ys returns the .
26490 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
264a0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 ult code] even w
264b0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 hen extended res
264c0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a ult codes are.**
264d0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
264e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
264f0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
26500 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
26510 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
26520 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
26530 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
26540 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
26550 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 r UTF-8 or UTF-1
26560 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 6 respectively..
26570 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
26580 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
26590 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
265a0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
265b0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ly..** The appli
265c0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 cation does not
265d0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 need to worry ab
265e0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 out freeing the
265f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
26600 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
26610 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
26620 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
26630 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
26640 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
26650 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
26660 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
26670 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ons.)^.**.** ^Th
26680 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 e sqlite3_errstr
26690 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
266a0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 urns the English
266b0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a -language text.*
266c0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 * that describes
266d0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 the [result cod
266e0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a e], as UTF-8..**
266f0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
26700 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
26710 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
26720 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
26730 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 .** and must not
26740 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 be freed by the
26750 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a application)^..
26760 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 **.** When the s
26770 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
26780 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e ding mode] is in
26790 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 use, it might b
267a0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 e the.** case th
267b0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f at a second erro
267c0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 r occurs on a se
267d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e parate thread in
267e0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 between.** the
267f0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 time of the firs
26800 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 t error and the
26810 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e call to these in
26820 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 terfaces..** Whe
26830 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 n that happens,
26840 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 the second error
26850 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 will be reporte
26860 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a d since these.**
26870 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 interfaces alwa
26880 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f ys report the mo
26890 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 st recent result
268a0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 . To avoid.** t
268b0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 his, each thread
268c0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c can obtain excl
268d0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 usive use of the
268e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
268f0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 ction] D.** by i
26900 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
26910 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 _mutex_enter]([s
26920 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
26930 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 (D)) before begi
26940 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 nning.** to use
26950 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b D and invoking [
26960 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 sqlite3_mutex_le
26970 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ave]([sqlite3_db
26980 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 _mutex](D)) afte
26990 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 r.** all calls t
269a0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 o the interfaces
269b0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 listed here are
269c0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a completed..**.*
269d0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 * If an interfac
269e0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c e fails with SQL
269f0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 ITE_MISUSE, that
26a00 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 means the inter
26a10 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f face.** was invo
26a20 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ked incorrectly
26a30 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
26a40 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 on. In that cas
26a50 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 e, the.** error
26a60 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 code and message
26a70 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 may or may not
26a80 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 be set..*/.SQLIT
26a90 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
26aa0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 3_errcode(sqlite
26ab0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 3 *db);.SQLITE_A
26ac0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
26ad0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
26ae0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 sqlite3 *db);.SQ
26af0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
26b00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
26b10 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 msg(sqlite3*);.S
26b20 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
26b30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 void *sqlite3_er
26b40 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 rmsg16(sqlite3*)
26b50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
26b60 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
26b70 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f _errstr(int);../
26b80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
26b90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a QL Statement Obj
26ba0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
26bb0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
26bc0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
26bd0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
26be0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
26bf0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
26c00 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
26c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
26c20 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
26c30 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 s variously know
26c40 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 n as a "prepared
26c50 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 statement" or a
26c60 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 .** "compiled SQ
26c70 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 L statement" or
26c80 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 simply as a "sta
26c90 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 tement"..**.** T
26ca0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 he life of a sta
26cb0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f tement object go
26cc0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b es something lik
26cd0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
26ce0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
26cf0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 e the object usi
26d00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
26d10 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 are_v2()] or a r
26d20 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 elated.** f
26d30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e unction..** <li>
26d40 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 Bind values to
26d50 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 [host parameters
26d60 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
26d70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
26d80 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
26d90 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
26da0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
26db0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
26dc0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
26dd0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
26de0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
26df0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
26e00 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
26e10 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
26e20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
26e30 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
26e40 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
26e50 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
26e60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
26e70 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
26e80 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 /ol>.**.** Refer
26e90 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f to documentatio
26ea0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
26eb0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f methods above fo
26ec0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
26ed0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
26ee0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
26ef0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
26f00 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
26f10 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
26f20 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a ime Limits.**.**
26f30 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 ^(This interfac
26f40 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
26f50 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
26f60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
26f70 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
26f80 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
26f90 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
26fa0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
26fb0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
26fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
26fd0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
26fe0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
26ff0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
27000 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
27010 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
27020 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
27030 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
27040 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
27050 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
27060 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
27070 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
27080 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
27090 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
270a0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 struct.)^.**.**
270b0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
270c0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
270d0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
270e0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
270f0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 ** ^(For each li
27100 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c mit category SQL
27110 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d ITE_LIMIT_<i>NAM
27120 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 E</i> there is a
27130 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 .** [limits | h
27140 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d ard upper bound]
27150 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 .** set at compi
27160 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 le-time by a C p
27170 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
27180 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d o called.** [lim
27190 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
271a0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a _<i>NAME</i>]..*
271b0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
271c0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
271d0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
271e0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
271f0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
27200 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
27210 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
27220 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
27230 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
27240 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 the hard upper b
27250 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 ound..**.** ^Reg
27260 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
27270 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 er or not the li
27280 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c mit was changed,
27290 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
272a0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 3_limit()] inter
272b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
272c0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
272d0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 the limit..** ^H
272e0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 ence, to find th
272f0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
27300 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f of a limit witho
27310 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a ut changing it,.
27320 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 ** simply invoke
27330 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
27340 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 with the third p
27350 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 arameter set to
27360 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 -1..**.** Run-ti
27370 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
27380 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
27390 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
273a0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
273b0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
273c0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
273d0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
273e0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
273f0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
27400 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
27410 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
27420 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
27430 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
27440 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
27450 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
27460 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
27470 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
27480 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
27490 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
274a0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
274b0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
274c0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
274d0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
274e0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
274f0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
27500 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
27510 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
27520 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
27530 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
27540 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
27550 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
27560 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
27570 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
27580 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
27590 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
275a0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
275b0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
275c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
275d0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
275e0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
275f0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
27600 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
27610 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
27620 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
27630 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
27640 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
27650 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
27660 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
27670 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
27680 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
27690 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
276a0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
276b0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
276c0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ses..*/.SQLITE_A
276d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c PI int sqlite3_l
276e0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
276f0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
27700 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
27710 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
27720 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
27730 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
27740 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
27750 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
27760 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
27770 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
27780 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
27790 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
277a0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
277b0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
277c0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
277d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
277e0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
277f0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
27800 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
27810 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
27820 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
27830 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
27840 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
27850 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
27860 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
27870 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
27880 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
27890 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
278a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
278b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
278c0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
278d0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
278e0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e w, in bytes.<dd>
278f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27900 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
27910 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
27920 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
27930 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
27940 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
27950 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
27960 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e ement, in bytes.
27970 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
27980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
27990 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 UMN]] ^(<dt>SQLI
279a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
279b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
279c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
279d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
279e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
279f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
27a00 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
27a10 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
27a20 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
27a30 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
27a40 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
27a50 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
27a60 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
27a70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27a80 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
27a90 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
27aa0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
27ab0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
27ac0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
27ad0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
27ae0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
27af0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a sion.</dd>)^.**.
27b00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
27b10 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
27b20 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
27b30 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
27b40 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c SELECT</dt>.** <
27b50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
27b60 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
27b70 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c n a compound SEL
27b80 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f ECT statement.</
27b90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
27ba0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
27bb0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 OP]] ^(<dt>SQLIT
27bc0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
27bd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
27be0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
27bf0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
27c00 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
27c10 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
27c20 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
27c30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
27c40 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 t. This limit i
27c50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a s not currently.
27c60 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f ** enforced, tho
27c70 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 ugh that might b
27c80 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 e added in some
27c90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
27ca0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 f.** SQLite.</dd
27cb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
27cc0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
27cd0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 N_ARG]] ^(<dt>SQ
27ce0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
27cf0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
27d00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
27d10 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
27d20 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
27d30 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
27d40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 [[SQLITE_LIMIT_A
27d50 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e TTACHED]] ^(<dt>
27d60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
27d70 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
27d80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
27d90 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
27da0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
27db0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a ases].)^</dd>.**
27dc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
27dd0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
27de0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 LENGTH]].** ^(<d
27df0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
27e00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
27e10 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
27e20 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
27e30 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
27e40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
27e50 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
27e60 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
27e70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
27e80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
27e90 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a ABLE_NUMBER]].**
27ea0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
27eb0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
27ec0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
27ed0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
27ee0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
27ef0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
27f00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
27f10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27f20 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
27f30 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
27f40 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
27f50 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a ER_DEPTH</dt>.**
27f60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
27f70 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 depth of recurs
27f80 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 ion for triggers
27f90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
27fa0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
27fb0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
27fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27fd0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
27fe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
27ff0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
28000 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
28010 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
28020 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
28030 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
28040 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
28050 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
28060 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
28070 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
28080 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
28090 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
280a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
280b0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
280c0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
280d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
280e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
280f0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
28100 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
28110 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
28120 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
28130 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
28140 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
28150 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
28160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
28170 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
28180 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 ER 9.#
28190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
281a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
281b0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a H 10.
281c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
281d0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 Compiling An SQ
281e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b L Statement.** K
281f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 EYWORDS: {SQL st
28200 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 atement compiler
28210 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 }.**.** To execu
28220 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c te an SQL query,
28230 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 it must first b
28240 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 e compiled into
28250 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 a byte-code.** p
28260 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 rogram using one
28270 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
28280 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
28290 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 rst argument, "d
282a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 b", is a [databa
282b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
282c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a btained from a.*
282d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 * prior successf
282e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
282f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
28300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
28310 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
28320 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 open16()]. The
28330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
28340 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 ion must not hav
28350 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a e been closed..*
28360 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
28370 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 argument, "zSql"
28380 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 , is the stateme
28390 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 nt to be compile
283a0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 d, encoded.** as
283b0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 either UTF-8 or
283c0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 UTF-16. The sq
283d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
283e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
283f0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 are_v2().** inte
28400 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 rfaces use UTF-8
28410 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 , and sqlite3_pr
28420 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 epare16() and sq
28430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
28440 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d v2().** use UTF-
28450 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 16..**.** ^If th
28460 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
28470 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 is less than ze
28480 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ro, then zSql is
28490 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a read up to the.
284a0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 ** first zero te
284b0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 rminator. ^If nB
284c0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
284d0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ive, then it is
284e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e the maximum.** n
284f0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 umber of bytes
28500 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 read from zSql.
28510 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 ^When nByte is
28520 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
28530 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 e.** zSql string
28540 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 ends at either
28550 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 the first '\000'
28560 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 or '\u0000' cha
28570 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 racter or.** the
28580 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 nByte-th byte,
28590 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
285a0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 first. If the ca
285b0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 ller knows.** th
285c0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 at the supplied
285d0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 string is nul-te
285e0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 rminated, then t
285f0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a here is a small.
28600 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 ** performance a
28610 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 dvantage to be g
28620 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 ained by passing
28630 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 an nByte parame
28640 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 ter that.** is e
28650 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 qual to the numb
28660 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
28670 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 he input string
28680 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e <i>including</i>
28690 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d .** the nul-term
286a0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 inator bytes as
286b0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 this saves SQLit
286c0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f e from having to
286d0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 .** make a copy
286e0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 of the input str
286f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 ing..**.** ^If p
28700 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c zTail is not NUL
28710 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 L then *pzTail i
28720 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
28730 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 to the first byt
28740 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e e.** past the en
28750 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 d of the first S
28760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 QL statement in
28770 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 zSql. These rou
28780 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f tines only.** co
28790 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 mpile the first
287a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
287b0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 l, so *pzTail is
287c0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
287d0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e o.** what remain
287e0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a s uncompiled..**
287f0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 .** ^*ppStmt is
28800 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
28810 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 a compiled [pre
28820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
28830 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 that can be.**
28840 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b executed using [
28850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
28860 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 ^If there is a
28870 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 n error, *ppStmt
28880 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 is set.** to NU
28890 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 LL. ^If the inp
288a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 ut text contains
288b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 no SQL (if the
288c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 input is an empt
288d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 y.** string or a
288e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a comment) then *
288f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f ppStmt is set to
28900 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 NULL..** The ca
28910 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 lling procedure
28920 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
28930 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 or deleting the
28940 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 compiled.** SQL
28950 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
28960 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
28970 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 e()] after it ha
28980 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
28990 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 it..** ppStmt ma
289a0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a y not be NULL..*
289b0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 *.** ^On success
289c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 , the sqlite3_pr
289d0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f epare() family o
289e0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 f routines retur
289f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a n [SQLITE_OK];.*
28a00 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b * otherwise an [
28a10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
28a20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
28a30 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
28a40 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 re_v2() and sqli
28a50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
28a60 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 () interfaces ar
28a70 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e.** recommended
28a80 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f for all new pro
28a90 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f grams. The two o
28aa0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 lder interfaces
28ab0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 are retained.**
28ac0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
28ad0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 mpatibility, but
28ae0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 their use is di
28af0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 scouraged..** ^I
28b00 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 n the "v2" inter
28b10 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 faces, the prepa
28b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
28b30 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 that is returne
28b40 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
28b50 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f stmt] object) co
28b60 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 ntains a copy of
28b70 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c the.** original
28b80 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 SQL text. This
28b90 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 causes the [sqli
28ba0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 te3_step()] inte
28bb0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 rface to.** beha
28bc0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 ve differently i
28bd0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a n three ways:.**
28be0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
28bf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 .** ^If the data
28c00 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
28c10 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 ges, instead of
28c20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
28c30 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a E_SCHEMA] as it.
28c40 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 ** always used t
28c50 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 o do, [sqlite3_s
28c60 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f tep()] will auto
28c70 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
28c80 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 ile the SQL.** s
28c90 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 tatement and try
28ca0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e to run it again
28cb0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
28cc0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 <li>.** ^When a
28cd0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 n error occurs,
28ce0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
28cf0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 will return one
28d00 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 of the detailed
28d10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 .** [error codes
28d20 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 ] or [extended e
28d30 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 rror codes]. ^T
28d40 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
28d50 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b or was that.** [
28d60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
28d70 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 would only retur
28d80 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c n a generic [SQL
28d90 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
28da0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 t code.** and th
28db0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f e application wo
28dc0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 uld have to make
28dd0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 a second call t
28de0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
28df0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 ()].** in order
28e00 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 to find the unde
28e10 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 rlying cause of
28e20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 the problem. Wit
28e30 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 h the "v2" prepa
28e40 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 re.** interfaces
28e50 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 , the underlying
28e60 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 reason for the
28e70 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
28e80 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a d immediately..*
28e90 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
28ea0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 i>.** ^If the sp
28eb0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 ecific value bou
28ec0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 nd to [parameter
28ed0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 | host paramete
28ee0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 r] in the .** WH
28ef0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 ERE clause might
28f00 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 influence the c
28f10 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 hoice of query p
28f20 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d lan for a statem
28f30 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ent,.** then the
28f40 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 statement will
28f50 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
28f60 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 recompiled, as
28f70 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 if there had bee
28f80 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 n .** a schema c
28f90 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 hange, on the fi
28fa0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 rst [sqlite3_st
28fb0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f ep()] call follo
28fc0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a wing any change.
28fd0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
28fe0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 e3_bind_text | b
28ff0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 indings] of that
29000 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a [parameter]. .*
29010 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 * ^The specific
29020 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 value of WHERE-c
29030 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 lause [parameter
29040 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 ] might influenc
29050 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 e the .** choice
29060 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 of query plan i
29070 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
29080 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 is the left-hand
29090 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 side of a [LIKE
290a0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f ].** or [GLOB] o
290b0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 perator or if th
290c0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 e parameter is c
290d0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e ompared to an in
290e0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 dexed column.**
290f0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f and the [SQLITE_
29100 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f ENABLE_STAT3] co
29110 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
29120 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a n is enabled..**
29130 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a the .** </li>.*
29140 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 * </ol>.*/.SQLIT
29150 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
29160 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 3_prepare(. sql
29170 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
29180 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
29190 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
291a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
291b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
291c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
291d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
291e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
291f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
29200 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
29210 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
29220 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
29230 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
29240 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
29250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
29260 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
29270 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
29280 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
29290 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
292a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
292b0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 prepare_v2(. sq
292c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
292d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
292e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
292f0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
29300 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
29310 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
29320 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
29330 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
29340 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
29350 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
29360 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
29370 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
29380 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
29390 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
293a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
293b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
293c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
293d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
293e0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 Sql */.);.SQLITE
293f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
29400 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
29410 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
29420 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
29430 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
29440 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
29450 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
29460 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
29470 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
29480 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
29490 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
294a0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
294b0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
294c0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
294d0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
294e0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
294f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
29500 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
29510 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
29520 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
29530 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
29540 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
29550 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
29560 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
29570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
29580 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
29590 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
295a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
295b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
295c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
295d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
295e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
295f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
29600 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
29610 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
29620 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
29630 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
29640 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
29650 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
29660 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
29670 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
29680 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
29690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
296a0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
296b0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e ment SQL.**.** ^
296c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
296d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
296e0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 trieve a saved c
296f0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 opy of the origi
29700 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 nal.** SQL text
29710 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 used to create a
29720 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29730 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 ment] if that st
29740 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 atement was.** c
29750 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
29760 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
29770 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
29780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
29790 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 6_v2()]..*/.SQLI
297a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
297b0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
297c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
297d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
297e0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
297f0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
29800 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
29810 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 atabase.**.** ^T
29820 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
29830 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 readonly(X) inte
29840 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
29850 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
29860 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 .** and only if
29870 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
29880 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 atement] X makes
29890 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 no direct chang
298a0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e es to.** the con
298b0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 tent of the data
298c0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a base file..**.**
298d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c Note that [appl
298e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
298f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f SQL functions] o
29900 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 r.** [virtual ta
29910 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e bles] might chan
29920 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
29930 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 indirectly as a
29940 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a side effect. .*
29950 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
29960 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
29970 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e on defines a fun
29980 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 ction "eval()" t
29990 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 hat .** calls [s
299a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
299b0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 then the followi
299c0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
299d0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 would.** change
299e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
299f0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d le through side-
29a00 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c effects:.**.** <
29a10 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
29a20 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 .** SELECT ev
29a30 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 al('DELETE FROM
29a40 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a t1') FROM t2;.**
29a50 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
29a60 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 ote>.**.** But b
29a70 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 ecause the [SELE
29a80 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f CT] statement do
29a90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
29aa0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a e database file.
29ab0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c ** directly, sql
29ac0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
29ad0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c ly() would still
29ae0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a return true.)^.
29af0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 **.** ^Transacti
29b00 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 on control state
29b10 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 ments such as [B
29b20 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c EGIN], [COMMIT],
29b30 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 [ROLLBACK],.**
29b40 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 [SAVEPOINT], and
29b50 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 [RELEASE] cause
29b60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
29b70 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
29b80 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 rn true,.** sinc
29b90 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 e the statements
29ba0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e themselves do n
29bb0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 ot actually modi
29bc0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
29bd0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 but.** rather th
29be0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 ey control the t
29bf0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 iming of when ot
29c00 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d her statements m
29c10 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 odify the .** da
29c20 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 tabase. ^The [A
29c30 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 TTACH] and [DETA
29c40 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 CH] statements a
29c50 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c lso cause.** sql
29c60 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
29c70 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
29c80 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 rue since, while
29c90 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 those statement
29ca0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 s.** change the
29cb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 configuration of
29cc0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
29cd0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 ection, they do
29ce0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 not make .** cha
29cf0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 nges to the cont
29d00 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
29d10 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 ase files on dis
29d20 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 k..*/.SQLITE_API
29d30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d int sqlite3_stm
29d40 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 t_readonly(sqlit
29d50 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
29d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29d70 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
29d80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
29d90 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 ent Has Been Res
29da0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 et.**.** ^The sq
29db0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
29dc0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 S) interface ret
29dd0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a urns true (non-z
29de0 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b ero) if the.** [
29df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29e00 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 nt] S has been s
29e10 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 tepped at least
29e20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b once using .** [
29e30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
29e40 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e but has not run
29e50 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
29e60 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a nd/or has not .*
29e70 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 * been reset usi
29e80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
29e90 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c t(S)]. ^The sql
29ea0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 ite3_stmt_busy(S
29eb0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 ).** interface r
29ec0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 eturns false if
29ed0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e S is a NULL poin
29ee0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f ter. If S is no
29ef0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 t a .** NULL poi
29f00 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 nter and is not
29f10 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
29f20 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 alid [prepared s
29f30 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a tatement].** obj
29f40 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ect, then the be
29f50 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
29f60 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
29f70 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a undesirable..**
29f80 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
29f90 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ce can be used i
29fa0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 n combination [s
29fb0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
29fc0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 ()].** to locate
29fd0 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 all prepared st
29fe0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 atements associa
29ff0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 ted with a datab
2a000 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 ase .** connecti
2a010 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e on that are in n
2a020 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 eed of being res
2a030 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 et. This can be
2a040 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 used,.** for ex
2a050 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f ample, in diagno
2a060 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f stic routines to
2a070 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 search for prep
2a080 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 ared .** stateme
2a090 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c nts that are hol
2a0a0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 ding a transacti
2a0b0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 on open..*/.SQLI
2a0c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2a0d0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c e3_stmt_busy(sql
2a0e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2a0f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 .** CAPI3REF: Dy
2a100 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 namically Typed
2a110 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 Value Object.**
2a120 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 KEYWORDS: {prote
2a130 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2a140 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 ue} {unprotected
2a150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a sqlite3_value}.
2a160 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
2a170 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 s the sqlite3_va
2a180 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 lue object to re
2a190 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 present all valu
2a1a0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 es.** that can b
2a1b0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 e stored in a da
2a1c0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 tabase table. SQ
2a1d0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 Lite uses dynami
2a1e0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 c typing.** for
2a1f0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 the values it st
2a200 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 ores. ^Values s
2a210 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 tored in sqlite3
2a220 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a _value objects.*
2a230 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 * can be integer
2a240 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e s, floating poin
2a250 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 t values, string
2a260 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c s, BLOBs, or NUL
2a270 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 L..**.** An sqli
2a280 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2a290 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 may be either "
2a2a0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 protected" or "u
2a2b0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 nprotected"..**
2a2c0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 Some interfaces
2a2d0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 require a protec
2a2e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2a2f0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 e. Other interf
2a300 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 aces.** will acc
2a310 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f ept either a pro
2a320 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 tected or an unp
2a330 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2a340 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 _value..** Every
2a350 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
2a360 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f accepts sqlite3_
2a370 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 value arguments
2a380 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 specifies.** whe
2a390 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 ther or not it r
2a3a0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 equires a protec
2a3b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2a3c0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 e..**.** The ter
2a3d0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 ms "protected" a
2a3e0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 nd "unprotected"
2a3f0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 refer to whethe
2a400 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 r or not.** a mu
2a410 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e tex is held. An
2a420 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 internal mutex
2a430 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 is held for a pr
2a440 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2a450 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
2a460 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 but no mutex is
2a470 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 held for an unpr
2a480 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2a490 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e e3_value object.
2a4a0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 If SQLite is c
2a4b0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 ompiled to be si
2a4c0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a ngle-threaded.**
2a4d0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 (with [SQLITE_T
2a4e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 HREADSAFE=0] and
2a4f0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 with [sqlite3_t
2a500 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 hreadsafe()] ret
2a510 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 urning 0).** or
2a520 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e if SQLite is run
2a530 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 in one of reduc
2a540 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a ed mutex modes .
2a550 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
2a560 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 G_SINGLETHREAD]
2a570 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
2a580 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a G_MULTITHREAD].*
2a590 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 * then there is
2a5a0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 no distinction b
2a5b0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 etween protected
2a5c0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 and unprotected
2a5d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
2a5e0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 e objects and th
2a5f0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 ey can be used i
2a600 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 nterchangeably.
2a610 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 However,.** for
2a620 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f maximum code po
2a630 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 rtability it is
2a640 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
2a650 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
2a660 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 still make the
2a670 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
2a680 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
2a690 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
2a6a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2a6b0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e bjects even when
2a6c0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 not strictly re
2a6d0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 quired..**.** ^T
2a6e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
2a6f0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 objects that ar
2a700 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 e passed as para
2a710 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a meters into the.
2a720 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
2a730 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f n of [applicatio
2a740 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
2a750 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f nctions] are pro
2a760 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 tected..** ^The
2a770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2a780 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
2a790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2a7a0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
2a7b0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 unprotected..**
2a7c0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 Unprotected sqli
2a7d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2a7e0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 s may only be us
2a7f0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 ed with.** [sqli
2a800 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
2a810 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2a820 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a _bind_value()]..
2a830 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
2a840 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c value_blob | sql
2a850 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
2a860 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 )] family of.**
2a870 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
2a880 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c re protected sql
2a890 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2a8a0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ts..*/.typedef s
2a8b0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 truct Mem sqlite
2a8c0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 3_value;../*.**
2a8d0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 CAPI3REF: SQL Fu
2a8e0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f nction Context O
2a8f0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
2a900 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 context in which
2a910 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
2a920 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f executes is sto
2a930 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c red in an.** sql
2a940 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
2a950 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 ect. ^A pointer
2a960 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 to an sqlite3_c
2a970 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a ontext object.**
2a980 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 is always first
2a990 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 parameter to [a
2a9a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2a9b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
2a9c0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 ]..** The applic
2a9d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
2a9e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2a9f0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 mentation will p
2aa00 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e ass this.** poin
2aa10 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f ter through into
2aa20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
2aa30 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 e3_result_int |
2aa40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 sqlite3_result()
2aa50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 ],.** [sqlite3_a
2aa60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
2aa70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 ()], [sqlite3_us
2aa80 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b er_data()],.** [
2aa90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
2aaa0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 db_handle()], [s
2aab0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2aac0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 ta()],.** and/or
2aad0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
2aae0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 xdata()]..*/.typ
2aaf0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2ab00 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 te3_context sqli
2ab10 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a te3_context;../*
2ab20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 .** CAPI3REF: Bi
2ab30 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 nding Values To
2ab40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2ab50 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a nts.** KEYWORDS:
2ab60 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2ab70 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
2ab80 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 rs} {host parame
2ab90 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 ter name}.** KEY
2aba0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 WORDS: {SQL para
2abb0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 meter} {SQL para
2abc0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 meters} {paramet
2abd0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a er binding}.**.*
2abe0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 * ^(In the SQL s
2abf0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e tatement text in
2ac00 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
2ac10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2ac20 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a d its variants,.
2ac30 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 ** literals may
2ac40 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 be replaced by a
2ac50 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 [parameter] tha
2ac60 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 t matches one of
2ac70 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 following.** te
2ac80 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c mplates:.**.** <
2ac90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a ul>.** <li> ?.*
2aca0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 * <li> ?NNN.**
2acb0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c <li> :VVV.** <l
2acc0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> @VVV.** <li>
2acd0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a $VVV.** </ul>.
2ace0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d **.** In the tem
2acf0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e plates above, NN
2ad00 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 N represents an
2ad10 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
2ad20 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 .** and VVV repr
2ad30 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e esents an alphan
2ad40 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 umeric identifie
2ad50 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 r.)^ ^The value
2ad60 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
2ad70 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
2ad80 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
2ad90 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
2ada0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
2adb0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
2adc0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
2add0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2ade0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
2adf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2ae00 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2ae10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2ae20 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 *() routines is
2ae30 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e always.** a poin
2ae40 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
2ae50 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2ae60 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a returned from.*
2ae70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2ae80 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
2ae90 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 variants..**.**
2aea0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
2aeb0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2aec0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 x of the SQL par
2aed0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
2aee0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f ..** ^The leftmo
2aef0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
2af00 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2af10 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 1. ^When the s
2af20 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c ame named.** SQL
2af30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
2af40 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
2af50 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 e, second and su
2af60 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
2af70 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
2af80 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
2af90 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
2afa0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 nce..** ^The ind
2afb0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 ex for named par
2afc0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
2afd0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
2afe0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
2aff0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2b000 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 dex()] API if de
2b010 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 sired. ^The ind
2b020 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
2b030 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
2b040 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
2b050 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c .** ^The NNN val
2b060 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 ue must be betwe
2b070 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 en 1 and the [sq
2b080 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
2b090 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c * parameter [SQL
2b0a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2b0b0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 LE_NUMBER] (defa
2b0c0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e ult value: 999).
2b0d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
2b0e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2b0f0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
2b100 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2b110 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f ..**.** ^(In tho
2b120 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 se routines that
2b130 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 have a fourth a
2b140 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c rgument, its val
2b150 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
2b160 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2b170 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 the parameter.
2b180 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 To be clear: the
2b190 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
2b1a0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 number of <u>by
2b1b0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 tes</u> in the v
2b1c0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 alue, not the nu
2b1d0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
2b1e0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 rs.)^.** ^If the
2b1f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2b200 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2b210 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
2b220 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2b230 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 ).** is negative
2b240 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 , then the lengt
2b250 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 h of the string
2b260 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 is.** the number
2b270 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 of bytes up to
2b280 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
2b290 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 erminator..** If
2b2a0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2b2b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2b2c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
2b2d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a negative, then.*
2b2e0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 * the behavior i
2b2f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
2b300 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 If a non-negativ
2b310 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2b320 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 er is provided t
2b330 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2b340 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ext().** or sqli
2b350 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2b360 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 ) then that para
2b370 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 meter must be th
2b380 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a e byte offset.**
2b390 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
2b3a0 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 erminator would
2b3b0 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 occur assuming t
2b3c0 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e he string were N
2b3d0 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 UL.** terminated
2b3e0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 . If any NUL ch
2b3f0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 aracters occur a
2b400 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c t byte offsets l
2b410 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 ess than .** the
2b420 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f value of the fo
2b430 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2b440 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e hen the resultin
2b450 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 g string value w
2b460 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 ill.** contain e
2b470 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 mbedded NULs. T
2b480 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 he result of exp
2b490 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 ressions involvi
2b4a0 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 ng strings.** wi
2b4b0 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 th embedded NULs
2b4c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2b4d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 *.** ^The fifth
2b4e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
2b4f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c te3_bind_blob(),
2b500 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2b510 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c xt(), and.** sql
2b520 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2b530 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 () is a destruct
2b540 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f or used to dispo
2b550 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
2b560 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 r.** string afte
2b570 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e r SQLite has fin
2b580 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 ished with it.
2b590 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 ^The destructor
2b5a0 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 is called.** to
2b5b0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
2b5c0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 LOB or string ev
2b5d0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 en if the call t
2b5e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
2b5f0 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 lob(),.** sqlite
2b600 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 3_bind_text(), o
2b610 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2b620 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 ext16() fails.
2b630 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
2b640 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a h argument is.**
2b650 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c the special val
2b660 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ue [SQLITE_STATI
2b670 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 C], then SQLite
2b680 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
2b690 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
2b6a0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e is in static, un
2b6b0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e managed space an
2b6c0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 d does not need
2b6d0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 to be freed..**
2b6e0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
2b6f0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 gument has the v
2b700 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 alue [SQLITE_TRA
2b710 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a NSIENT], then.**
2b720 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 SQLite makes it
2b730 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
2b740 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 py of the data i
2b750 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f mmediately, befo
2b760 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 re.** the sqlite
2b770 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2b780 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ne returns..**.*
2b790 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2b7a0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 ind_zeroblob() r
2b7b0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 outine binds a B
2b7c0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 LOB of length N
2b7d0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 that.** is fille
2b7e0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 d with zeroes.
2b7f0 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 ^A zeroblob uses
2b800 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 a fixed amount
2b810 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 of memory.** (ju
2b820 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f st an integer to
2b830 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 hold its size)
2b840 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e while it is bein
2b850 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 g processed..**
2b860 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e Zeroblobs are in
2b870 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 tended to serve
2b880 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 as placeholders
2b890 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a for BLOBs whose.
2b8a0 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 ** content is la
2b8b0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e ter written usin
2b8c0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c g.** [sqlite3_bl
2b8d0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
2b8e0 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 ental BLOB I/O]
2b8f0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 routines..** ^A
2b900 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 negative value f
2b910 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 or the zeroblob
2b920 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 results in a zer
2b930 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a o-length BLOB..*
2b940 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 *.** ^If any of
2b950 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
2b960 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 _*() routines ar
2b970 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 e called with a
2b980 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2b990 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 for the [prepare
2b9a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 d statement] or
2b9b0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 with a prepared
2b9c0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 statement for wh
2b9d0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ich.** [sqlite3_
2b9e0 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e step()] has been
2b9f0 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 called more rec
2ba00 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 ently than [sqli
2ba10 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a te3_reset()],.**
2ba20 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 then the call w
2ba30 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
2ba40 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 TE_MISUSE]. If
2ba50 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 any sqlite3_bind
2ba60 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 _().** routine i
2ba70 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 s passed a [prep
2ba80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2ba90 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 that has been fi
2baa0 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 nalized, the.**
2bab0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
2bac0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 ned and probably
2bad0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 harmful..**.**
2bae0 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f ^Bindings are no
2baf0 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 t cleared by the
2bb00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2bb10 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e )] routine..** ^
2bb20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
2bb30 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
2bb40 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
2bb50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2bb60 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 ind_* routines r
2bb70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
2bb80 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 ] on success or
2bb90 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
2bba0 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 e] if anything g
2bbb0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b oes wrong..** ^[
2bbc0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 SQLITE_RANGE] is
2bbd0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
2bbe0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
2bbf0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
2bc00 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e nge. ^[SQLITE_N
2bc10 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 OMEM] is returne
2bc20 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 d if malloc() fa
2bc30 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ils..**.** See a
2bc40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2bc50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2bc60 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
2bc70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2bc80 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
2bc90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2bca0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2bcb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2bcc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2bcd0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2bce0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
2bcf0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 oid*, int n, voi
2bd00 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2bd10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2bd20 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 ite3_bind_double
2bd30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2bd40 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 int, double);.SQ
2bd50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2bd60 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
2bd70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2bd80 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
2bd90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
2bda0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
2bdb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
2bdc0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 lite3_int64);.SQ
2bdd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2bde0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 ite3_bind_null(s
2bdf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2be00 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 t);.SQLITE_API i
2be10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2be20 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
2be30 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
2be40 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
2be50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2be60 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2be70 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2be80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2be90 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
2bea0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
2beb0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
2bec0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
2bed0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
2bee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2bef0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
2bf00 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
2bf10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2bf20 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
2bf30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2bf40 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
2bf50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 I3REF: Number Of
2bf60 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a SQL Parameters.
2bf70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
2bf80 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
2bf90 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
2bfa0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
2bfb0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
2bfc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2bfd0 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
2bfe0 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
2bff0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
2c000 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
2c010 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
2c020 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
2c030 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
2c040 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
2c050 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
2c060 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
2c070 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
2c080 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
2c090 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
2c0a0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 ^(This routine a
2c0b0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
2c0c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2c0d0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
2c0e0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
2c0f0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
2c100 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
2c110 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
2c120 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
2c130 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
2c140 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
2c150 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
2c160 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 ?NNN form are us
2c170 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
2c180 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
2c190 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 list.)^.**.** Se
2c1a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2c1b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2c1c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2c1d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2c1e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
2c1f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2c200 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2c210 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2c220 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2c230 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2c240 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
2c250 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2c260 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
2c270 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
2c280 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c r.**.** ^The sql
2c290 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c2a0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e ter_name(P,N) in
2c2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
2c2c0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ** the name of t
2c2d0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 he N-th [SQL par
2c2e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b ameter] in the [
2c2f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c300 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 nt] P..** ^(SQL
2c310 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
2c320 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 e form "?NNN" or
2c330 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2c340 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 " or "$AAA".** h
2c350 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 ave a name which
2c360 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 is the string "
2c370 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2c380 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2c390 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 AA".** respectiv
2c3a0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ely..** In other
2c3b0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 words, the init
2c3c0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f ial ":" or "$" o
2c3d0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 r "@" or "?".**
2c3e0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 is included as p
2c3f0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e art of the name.
2c400 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 )^.** ^Parameter
2c410 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f s of the form "?
2c420 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c " without a foll
2c430 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 owing integer ha
2c440 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e ve no name.** an
2c450 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 d are referred t
2c460 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 o as "nameless"
2c470 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 or "anonymous pa
2c480 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a rameters"..**.**
2c490 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 ^The first host
2c4a0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
2c4b0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
2c4c0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t 0..**.** ^If t
2c4d0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 he value N is ou
2c4e0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 t of range or if
2c4f0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 the N-th parame
2c500 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 ter is.** namele
2c510 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 ss, then NULL is
2c520 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 returned. ^The
2c530 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2c540 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e is.** always in
2c550 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
2c560 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 even if the name
2c570 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a d parameter was.
2c580 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 ** originally sp
2c590 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 ecified as UTF-1
2c5a0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 6 in [sqlite3_pr
2c5b0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a epare16()] or.**
2c5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c5d0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a e16_v2()]..**.**
2c5e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2c5f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2c600 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
2c610 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2c620 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2c630 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2c640 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2c650 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2c660 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2c670 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 char *sqlite3_b
2c680 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2c690 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2c6a0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , int);../*.** C
2c6b0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f API3REF: Index O
2c6c0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 f A Parameter Wi
2c6d0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a th A Given Name.
2c6e0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
2c6f0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 e index of an SQ
2c700 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 L parameter give
2c710 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 n its name. ^Th
2c720 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
2c730 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
2c740 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
2c750 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
2c760 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
2c770 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2c780 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
2c790 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 ^A zero.** is r
2c7a0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 eturned if no ma
2c7b0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 tching parameter
2c7c0 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 is found. ^The
2c7d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 parameter.** na
2c7e0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e me must be given
2c7f0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 in UTF-8 even i
2c800 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 f the original s
2c810 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 tatement.** was
2c820 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 prepared from UT
2c830 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 F-16 text using
2c840 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2c850 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
2c860 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2c870 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
2c880 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
2c890 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2c8a0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
2c8b0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
2c8c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2c8d0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
2c8e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
2c8f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2c900 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 eter_index(sqlit
2c910 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 e3_stmt*, const
2c920 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f char *zName);../
2c930 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2c940 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 eset All Binding
2c950 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 s On A Prepared
2c960 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
2c970 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 ^Contrary to the
2c980 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 intuition of ma
2c990 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ny, [sqlite3_res
2c9a0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 et()] does not r
2c9b0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c eset.** the [sql
2c9c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
2c9d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 bindings] on a
2c9e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c9f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 ent]..** ^Use th
2ca00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 is routine to re
2ca10 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 set all host par
2ca20 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e ameters to NULL.
2ca30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2ca40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 nt sqlite3_clear
2ca50 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
2ca60 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2ca70 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2ca80 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
2ca90 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
2caa0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e ** ^Return the n
2cab0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2cac0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
2cad0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 et returned by t
2cae0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
2caf0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 statement]. ^Thi
2cb00 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
2cb10 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 s 0 if pStmt is
2cb20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d an SQL.** statem
2cb30 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f ent that does no
2cb40 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 t return data (f
2cb50 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 or example an [U
2cb60 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 PDATE])..**.** S
2cb70 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2cb80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 3_data_count()].
2cb90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2cba0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2cbb0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2cbc0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2cbd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
2cbe0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 lumn Names In A
2cbf0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a Result Set.**.**
2cc00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2cc10 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
2cc20 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
2cc30 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
2cc40 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
2cc50 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
2cc60 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
2cc70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
2cc80 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
2cc90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2cca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
2ccb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
2ccc0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
2ccd0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2cce0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
2ccf0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2cd00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2cd10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
2cd20 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ng. ^The first
2cd30 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2cd40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2cd50 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
2cd60 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
2cd70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2cd80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
2cd90 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
2cda0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
2cdb0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
2cdc0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
2cdd0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 0..**.** ^The re
2cde0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
2cdf0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
2ce00 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
2ce10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ce20 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
2ce30 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
2ce40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2ce50 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2ce60 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2ce70 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2ce80 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2ce90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2cea0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2ceb0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2cec0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
2ced0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
2cee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2cef0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
2cf00 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
2cf10 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
2cf20 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c n..**.** ^If sql
2cf30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
2cf40 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
2cf50 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
2cf60 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
2cf70 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
2cf80 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
2cf90 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
2cfa0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
2cfb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
2cfc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
2cfd0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 ^The name of a r
2cfe0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
2cff0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
2d000 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
2d010 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
2d020 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
2d030 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
2d040 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
2d050 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
2d060 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
2d070 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
2d080 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
2d090 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
2d0a0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
2d0b0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
2d0c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2d0d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2d0e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 olumn_name(sqlit
2d0f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
2d100 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2d110 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2d120 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 _column_name16(s
2d130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2d140 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t N);../*.** CAP
2d150 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 I3REF: Source Of
2d160 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 Data In A Query
2d170 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 Result.**.** ^T
2d180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 hese routines pr
2d190 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f ovide a means to
2d1a0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 determine the d
2d1b0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 atabase, table,
2d1c0 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c and.** table col
2d1d0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 umn that is the
2d1e0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 origin of a part
2d1f0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f icular result co
2d200 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 lumn in.** [SELE
2d210 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a CT] statement..*
2d220 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
2d230 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 he database or t
2d240 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 able or column c
2d250 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 an be returned a
2d260 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 s.** either a UT
2d270 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 F-8 or UTF-16 st
2d280 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 ring. ^The _dat
2d290 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 abase_ routines
2d2a0 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 return.** the da
2d2b0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 tabase name, the
2d2c0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 _table_ routine
2d2d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 s return the tab
2d2e0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 le name, and.**
2d2f0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 the origin_ rout
2d300 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
2d310 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 column name..**
2d320 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
2d330 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e ring is valid un
2d340 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 til the [prepare
2d350 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 d statement] is
2d360 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 destroyed.** usi
2d370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
2d380 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
2d390 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2d3a0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a s automatically.
2d3b0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 ** reprepared by
2d3c0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 the first call
2d3d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
2d3e0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 ()] for a partic
2d3f0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 ular run.** or u
2d400 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e ntil the same in
2d410 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 formation is req
2d420 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 uested.** again
2d430 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 in a different e
2d440 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e ncoding..**.** ^
2d450 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e The names return
2d460 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 ed are the origi
2d470 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e nal un-aliased n
2d480 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 ames of the.** d
2d490 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 atabase, table,
2d4a0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a and column..**.*
2d4b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
2d4c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 ument to these i
2d4d0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b nterfaces is a [
2d4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d4f0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 nt]..** ^These f
2d500 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
2d510 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
2d520 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 t the Nth result
2d530 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 column returned
2d540 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 by.** the state
2d550 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 ment, where N is
2d560 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 the second func
2d570 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a tion argument..*
2d580 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 * ^The left-most
2d590 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d column is colum
2d5a0 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f n 0 for these ro
2d5b0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 utines..**.** ^I
2d5c0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
2d5d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
2d5e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e statement is an
2d5f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a expression or.*
2d600 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 * subquery and i
2d610 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 s not a column v
2d620 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f alue, then all o
2d630 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
2d640 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c s return.** NULL
2d650 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
2d660 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 e might also ret
2d670 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 urn NULL if a me
2d680 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
2d690 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e error.** occurs.
2d6a0 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 ^Otherwise, th
2d6b0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 ey return the na
2d6c0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 me of the attach
2d6d0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 ed database, tab
2d6e0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e le,.** or column
2d6f0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 that query resu
2d700 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 lt column was ex
2d710 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a tracted from..**
2d720 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c .** ^As with all
2d730 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 other SQLite AP
2d740 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 Is, those whose
2d750 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 names end with "
2d760 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 16" return.** UT
2d770 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 F-16 encoded str
2d780 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 ings and the oth
2d790 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 er functions ret
2d7a0 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a urn UTF-8..**.**
2d7b0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 ^These APIs are
2d7c0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
2d7d0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 if the library w
2d7e0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
2d7f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
2d800 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
2d810 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f TADATA] C-prepro
2d820 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a cessor symbol..*
2d830 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
2d840 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
2d850 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
2d860 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
2d870 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a gainst the same.
2d880 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
2d890 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e ement and column
2d8a0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
2d8b0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
2d8c0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 ts are.** undefi
2d8d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 ned..**.** If tw
2d8e0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2d8f0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
2d900 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 re.** [sqlite3_c
2d910 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
2d920 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 ame | column met
2d930 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 adata interfaces
2d940 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ].** for the sam
2d950 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2d960 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c ement] and resul
2d970 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 t column.** at t
2d980 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
2d990 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
2d9a0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
2d9b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2d9c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2d9d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
2d9e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
2d9f0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 *,int);.SQLITE_A
2da00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
2da10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2da20 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 tabase_name16(sq
2da30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2da40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2da50 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2da60 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
2da70 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2da80 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2da90 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2daa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
2dab0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 le_name16(sqlite
2dac0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2dad0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
2dae0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
2daf0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
2db00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2db10 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2db20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2db30 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
2db40 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2db50 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
2db60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
2db70 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
2db80 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
2db90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 .**.** ^(The fir
2dba0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2dbb0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2dbc0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 ement]..** If th
2dbd0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 is statement is
2dbe0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
2dbf0 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 ment and the Nth
2dc00 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a column of the.*
2dc10 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c * returned resul
2dc20 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 t set of that [S
2dc30 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c ELECT] is a tabl
2dc40 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e e column (not an
2dc50 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
2dc60 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e r subquery) then
2dc70 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2dc80 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a pe of the table.
2dc90 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 ** column is ret
2dca0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 urned.)^ ^If th
2dcb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2dcc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 the result set i
2dcd0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 s an.** expressi
2dce0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 on or subquery,
2dcf0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e then a NULL poin
2dd00 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
2dd10 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 .** ^The returne
2dd20 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
2dd30 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 ys UTF-8 encoded
2dd40 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 ..**.** ^(For ex
2dd50 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 ample, given the
2dd60 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
2dd70 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 :.**.** CREATE T
2dd80 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 ABLE t1(c1 VARIA
2dd90 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 NT);.**.** and t
2dda0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 he following sta
2ddb0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
2ddc0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c piled:.**.** SEL
2ddd0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 ECT c1 + 1, c1 F
2dde0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 ROM t1;.**.** th
2ddf0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
2de00 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
2de10 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
2de20 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 the second resu
2de30 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d lt.** column (i=
2de40 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
2de50 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
2de60 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
2de70 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a umn (i==0).)^.**
2de80 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
2de90 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
2dea0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a e typing. ^So j
2deb0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f ust because a co
2dec0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 lumn.** is decla
2ded0 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 red to contain a
2dee0 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 particular type
2def0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 does not mean t
2df00 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 hat the.** data
2df10 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 stored in that c
2df20 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 olumn is of the
2df30 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 declared type.
2df40 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 SQLite is.** str
2df50 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 ongly typed, but
2df60 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 the typing is d
2df70 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 ynamic not stati
2df80 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 c. ^Type.** is
2df90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2dfa0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 individual value
2dfb0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 s, not with the
2dfc0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 containers.** us
2dfd0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 ed to hold those
2dfe0 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 values..*/.SQLI
2dff0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
2e000 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
2e010 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 n_decltype(sqlit
2e020 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2e030 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2e040 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2e050 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2e060 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2e070 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e080 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2e090 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2e0a0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2e0b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e0c0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2e0d0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2e0e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2e0f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2e100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2e110 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2e120 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2e130 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2e140 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2e150 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e160 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2e170 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2e180 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2e190 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2e1a0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2e1b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2e1c0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2e1d0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2e1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2e1f0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2e200 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2e210 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2e220 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2e230 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2e240 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2e250 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2e260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2e270 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2e280 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2e290 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2e2a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2e2b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2e2c0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2e2d0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2e2e0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2e2f0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2e300 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2e310 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2e320 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2e330 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2e340 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2e350 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2e360 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2e370 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2e380 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2e390 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2e3a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2e3b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2e3c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2e3d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2e3e0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2e3f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2e400 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2e410 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2e420 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2e430 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2e440 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2e450 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2e460 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2e470 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2e480 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2e490 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2e4a0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2e4b0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2e4c0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2e4d0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2e4e0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2e4f0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2e500 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2e510 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2e520 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2e530 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2e540 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2e550 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2e560 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2e570 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2e580 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2e590 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2e5a0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2e5b0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2e5c0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2e5d0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2e5e0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2e5f0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2e600 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2e610 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2e620 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2e630 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2e640 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2e650 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2e660 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2e670 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2e680 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2e690 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2e6a0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2e6b0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2e6c0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2e6d0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2e6e0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2e6f0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2e700 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2e710 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2e720 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2e730 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2e740 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2e750 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2e760 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2e770 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2e780 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2e790 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2e7a0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2e7b0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2e7c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2e7d0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2e7e0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2e7f0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2e800 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2e810 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2e820 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2e830 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2e840 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2e850 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2e860 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2e870 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2e880 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2e890 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2e8a0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2e8b0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2e8c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2e8d0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2e8e0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2e8f0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2e900 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2e910 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2e920 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2e930 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2e940 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2e950 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2e960 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2e970 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2e980 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2e990 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2e9a0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2e9b0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2e9c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2e9d0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2e9e0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2e9f0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2ea00 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2ea10 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2ea20 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2ea30 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2ea40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2ea50 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2ea60 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2ea70 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2ea80 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2ea90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2eaa0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2eab0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2eac0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2ead0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2eae0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2eaf0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2eb00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2eb10 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2eb20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2eb30 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2eb40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2eb50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2eb60 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2eb70 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2eb80 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2eb90 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2eba0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2ebb0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2ebc0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2ebd0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2ebe0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2ebf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2ec00 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2ec10 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2ec20 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2ec30 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2ec40 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2ec50 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2ec60 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2ec70 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2ec80 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2ec90 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2eca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2ecb0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2ecc0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2ecd0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2ece0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2ecf0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2ed00 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2ed10 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2ed20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2ed30 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2ed40 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2ed50 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2ed60 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2ed70 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2ed80 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2ed90 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2eda0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2edb0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2edc0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2edd0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2ede0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2edf0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2ee00 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2ee10 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2ee20 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2ee30 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2ee40 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2ee50 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2ee60 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2ee70 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2ee80 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2ee90 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2eea0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2eeb0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2eec0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2eed0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2eee0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2eef0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2ef00 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2ef10 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2ef20 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2ef30 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2ef40 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2ef50 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2ef60 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2ef70 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2ef80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2ef90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2efa0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2efb0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2efc0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2efd0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2efe0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2eff0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2f000 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2f010 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2f020 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2f030 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2f040 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2f050 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2f060 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2f070 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2f080 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2f090 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2f0a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2f0b0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2f0c0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2f0d0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2f0e0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2f0f0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2f100 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2f110 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2f120 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2f130 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2f140 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2f150 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2f160 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2f170 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2f180 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2f190 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2f1a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2f1b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 nt sqlite3_step(
2f1c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2f1d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f1e0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d Number of colum
2f1f0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 ns in a result s
2f200 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 et.**.** ^The sq
2f210 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2f220 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
2f230 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2f240 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
2f250 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f he.** current ro
2f260 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
2f270 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 set of [prepared
2f280 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2f290 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 * ^If prepared s
2f2a0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 tatement P does
2f2b0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 not have results
2f2c0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e ready to return
2f2d0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 .** (via calls t
2f2e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
2f2f0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 olumn_int | sqli
2f300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 te3_column_*()]
2f310 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
2f320 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 ) then sqlite3_d
2f330 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 ata_count(P) ret
2f340 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 urns 0..** ^The
2f350 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2f360 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c nt(P) routine al
2f370 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 so returns 0 if
2f380 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e P is a NULL poin
2f390 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ter..** ^The sql
2f3a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2f3b0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 P) routine retur
2f3c0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 ns 0 if the prev
2f3d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 ious call to.**
2f3e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 [sqlite3_step](P
2f3f0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 ) returned [SQLI
2f400 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 TE_DONE]. ^The
2f410 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2f420 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 nt(P).** will re
2f430 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 turn non-zero if
2f440 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2f450 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d o [sqlite3_step]
2f460 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 (P) returned.**
2f470 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 [SQLITE_ROW], ex
2f480 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 cept in the case
2f490 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 of the [PRAGMA
2f4a0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 incremental_vacu
2f4b0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 um].** where it
2f4c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a always returns z
2f4d0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 ero since each s
2f4e0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 tep of that mult
2f4f0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 i-step.** pragma
2f500 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d returns 0 colum
2f510 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ns of data..**.*
2f520 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2f530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2f540 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 t()].*/.SQLITE_A
2f550 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 PI int sqlite3_d
2f560 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 ata_count(sqlite
2f570 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2f580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2f590 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 Fundamental Dat
2f5a0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 atypes.** KEYWOR
2f5b0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a DS: SQLITE_TEXT.
2f5c0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 **.** ^(Every va
2f5d0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
2f5e0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
2f5f0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
2f600 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
2f610 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
2f620 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
2f630 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
2f640 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
2f650 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
2f660 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
2f670 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
2f680 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
2f690 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
2f6a0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
2f6b0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
2f6c0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
2f6d0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
2f6e0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
2f6f0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
2f700 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
2f710 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
2f720 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
2f730 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
2f740 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
2f750 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
2f760 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
2f770 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2f780 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
2f790 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a ITE3_TEXT, not.*
2f7a0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a * SQLITE_TEXT..*
2f7b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2f7c0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 _INTEGER 1.#def
2f7d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ine SQLITE_FLOAT
2f7e0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2f7f0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a LITE_BLOB 4.
2f800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
2f810 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 ULL 5.#ifdef
2f820 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 SQLITE_TEXT.# u
2f830 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 ndef SQLITE_TEXT
2f840 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
2f850 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 SQLITE_TEXT
2f860 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 3.#endif.#define
2f870 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 SQLITE3_TEXT
2f880 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3../*.** CAPI3
2f890 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 REF: Result Valu
2f8a0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a es From A Query.
2f8b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
2f8c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
2f8d0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 tions}.**.** The
2f8e0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d se routines form
2f8f0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 the "result set
2f900 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a " interface..**.
2f910 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2f920 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d es return inform
2f930 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 ation about a si
2f940 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
2f950 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 he current.** re
2f960 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 sult row of a qu
2f970 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 ery. ^In every
2f980 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 case the first a
2f990 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2f9a0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
2f9b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f9c0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
2f9d0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 g evaluated (the
2f9e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
2f9f0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 .** that was ret
2fa00 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
2fa10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2fa20 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 ] or one of its
2fa30 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 variants).** and
2fa40 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
2fa50 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2fa60 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 x of the column
2fa70 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d for which inform
2fa80 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
2fa90 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 be returned. ^Th
2faa0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
2fab0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
2fac0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 set has the inde
2fad0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d x 0..** ^The num
2fae0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2faf0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e n the result can
2fb00 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
2fb10 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
2fb20 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d _column_count()]
2fb30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 ..**.** If the S
2fb40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
2fb50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
2fb60 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 point to a valid
2fb70 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a row, or if the.
2fb80 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 ** column index
2fb90 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
2fba0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 the result is u
2fbb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
2fbc0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 se routines may
2fbd0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 only be called w
2fbe0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 hen the most rec
2fbf0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
2fc00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2fc10 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 has returned [SQ
2fc20 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 LITE_ROW] and ne
2fc30 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
2fc40 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 3_reset()] nor [
2fc50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2fc60 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 ()] have been ca
2fc70 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c lled subsequentl
2fc80 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 y..** If any of
2fc90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
2fca0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 re called after
2fcb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2fcc0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
2fcd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2fce0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 after [sqlite3_s
2fcf0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
2fd00 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 ned.** something
2fd10 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
2fd20 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 ITE_ROW], the re
2fd30 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2fd40 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 ned..** If [sqli
2fd50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
2fd60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2fd70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
2fd80 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 alize()].** are
2fd90 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 called from a di
2fda0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 fferent thread w
2fdb0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 hile any of thes
2fdc0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 e routines.** ar
2fdd0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 e pending, then
2fde0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
2fdf0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2fe00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
2fe10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
2fe20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ine returns the.
2fe30 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 ** [SQLITE_INTEG
2fe40 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f ER | datatype co
2fe50 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 de] for the init
2fe60 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a ial data type.**
2fe70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 of the result c
2fe80 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 olumn. ^The ret
2fe90 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f urned value is o
2fea0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e ne of [SQLITE_IN
2feb0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 TEGER],.** [SQLI
2fec0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 TE_FLOAT], [SQLI
2fed0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 TE_TEXT], [SQLIT
2fee0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c E_BLOB], or [SQL
2fef0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 ITE_NULL]. The
2ff00 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
2ff10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2ff20 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e umn_type() is on
2ff30 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 ly meaningful if
2ff40 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 no type.** conv
2ff50 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 ersions have occ
2ff60 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 urred as describ
2ff70 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 ed below. After
2ff80 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
2ff90 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 on,.** the value
2ffa0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2ffb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2ffc0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
2ffd0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 Future.** vers
2ffe0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
2fff0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 ay change the be
30000 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 havior of sqlite
30010 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 3_column_type().
30020 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 ** following a t
30030 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ype conversion..
30040 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
30050 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
30060 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 r UTF-8 string t
30070 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
30080 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a column_bytes().*
30090 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
300a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
300b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c bytes in that BL
300c0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a OB or string..**
300d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
300e0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 is a UTF-16 stri
300f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
30100 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
30110 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
30120 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 string to UTF-8
30130 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
30140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
30150 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
30160 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
30170 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
30180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30190 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b ytes() uses.** [
301a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
301b0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
301c0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
301d0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 TF-8 string and
301e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
301f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
30200 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
30210 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
30220 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 is NULL, then s
30230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30240 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 tes() returns ze
30250 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ro..**.** ^If th
30260 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c e result is a BL
30270 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 OB or UTF-16 str
30280 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
30290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
302a0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 s16().** routine
302b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
302c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
302d0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
302e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
302f0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d result is a UTF-
30300 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 8 string, then s
30310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30320 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 tes16() converts
30330 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
30340 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 o UTF-16 and the
30350 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
30360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a mber of bytes..*
30370 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
30380 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
30390 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
303a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
303b0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
303c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
303d0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
303e0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 alue to a UTF-16
303f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
30400 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
30410 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
30420 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
30430 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
30440 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
30450 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
30460 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 6() returns zero
30470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c ..**.** ^The val
30480 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
30490 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
304a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a bytes()] and .**
304b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
304c0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e _bytes16()] do n
304d0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a ot include the z
304e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 ero terminators
304f0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 at the end.** of
30500 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 the string. ^F
30510 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 or clarity: the
30520 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
30530 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
30540 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
30550 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 nd [sqlite3_colu
30560 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 mn_bytes16()] ar
30570 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a e the number of.
30580 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 ** bytes in the
30590 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 string, not the
305a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
305b0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 ters..**.** ^Str
305c0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
305d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
305e0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 text() and sqlit
305f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30600 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 (),.** even empt
30610 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 y strings, are a
30620 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
30630 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 nated. ^The ret
30640 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f urn.** value fro
30650 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e m sqlite3_column
30660 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 _blob() for a ze
30670 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 ro-length BLOB i
30680 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
30690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a ..**.** ^The obj
306a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 ect returned by
306b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
306c0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a value()] is an.*
306d0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 * [unprotected s
306e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
306f0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 ject. An unprot
30700 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
30710 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 lue object.** ma
30720 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 y only be used w
30730 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e ith [sqlite3_bin
30740 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
30750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
30760 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
30770 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
30780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30790 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
307a0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
307b0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
307c0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
307d0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
307e0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
307f0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
30800 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
30810 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
30820 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
30830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30840 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 bytes()], then t
30850 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
30860 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
30870 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
30880 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
30890 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
308a0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
308b0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
308c0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
308d0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
308e0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
308f0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
30900 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
30910 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
30920 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
30930 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
30940 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
30950 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
30960 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
30970 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
30980 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
30990 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
309a0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
309b0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
309c0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
309d0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
309e0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
309f0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
30a00 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
30a10 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
30a20 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
30a30 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
30a40 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
30a50 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
30a60 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
30a70 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
30a80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
30a90 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
30aa0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
30ab0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
30ac0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
30ad0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f LL <td> BLO
30ae0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 B <td> Result
30af0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
30b00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
30b10 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 EGER <td> FLOA
30b20 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 T <td> Conver
30b30 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 t from integer t
30b40 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c o float.** <tr><
30b50 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
30b60 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
30b70 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
30b80 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a of the integer.
30b90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
30ba0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 GER <td> BLOB
30bb0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 <td> Same as
30bc0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a INTEGER->TEXT.*
30bd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
30be0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 T <td> INTEGER
30bf0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
30c00 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e from float to in
30c10 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
30c20 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
30c30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
30c40 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
30c50 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
30c60 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
30c70 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
30c80 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f <td> Same as FLO
30c90 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e AT->TEXT.** <tr>
30ca0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
30cb0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
30cc0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 > Use atoi().**
30cd0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
30ce0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
30cf0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 <td> Use atof()
30d00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
30d10 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
30d20 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
30d30 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
30d40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
30d50 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
30d60 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
30d70 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 n use atoi().**
30d80 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
30d90 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
30da0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
30db0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
30dc0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
30dd0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
30de0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
30df0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
30e00 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
30e10 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
30e20 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
30e30 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 .** The table ab
30e40 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 ove makes refere
30e50 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 nce to standard
30e60 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 C library functi
30e70 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e ons atoi().** an
30e80 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 d atof(). SQLit
30e90 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c e does not reall
30ea0 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 y use these func
30eb0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 tions. It has i
30ec0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 ts.** own equiva
30ed0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f lent internal ro
30ee0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f utines. The ato
30ef0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e i() and atof() n
30f00 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 ames are.** used
30f10 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f in the table fo
30f20 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 r brevity and be
30f30 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 cause they are f
30f40 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a amiliar to most.
30f50 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 ** C programmers
30f60 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
30f70 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 t when type conv
30f80 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 ersions occur, p
30f90 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
30fa0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c by prior.** cal
30fb0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
30fc0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c lumn_blob(), sql
30fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30fe0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 (), and/or.** sq
30ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
31000 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 t16() may be inv
31010 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 alidated..** Typ
31020 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e e conversions an
31030 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 d pointer invali
31040 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 dations might oc
31050 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f cur.** in the fo
31060 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a llowing cases:.*
31070 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
31080 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
31090 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 ntent is a BLOB
310a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
310b0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 mn_text() or.**
310c0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
310d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
310e0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d called. A zero-
310f0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 terminator might
31100 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f .** need to
31110 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 be added to the
31120 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a string.</li>.**
31130 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
31140 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
31150 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 -8 text and sqli
31160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31170 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 16() or.**
31180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31190 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
311a0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
311b0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
311c0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
311d0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 -16.</li>.** <li
311e0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
311f0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 ntent is UTF-16
31200 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
31210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
31220 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
31230 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
31240 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
31250 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
31260 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
31270 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 to UTF-8.</li
31280 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
31290 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 ^Conversions be
312a0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 tween UTF-16be a
312b0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 nd UTF-16le are
312c0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 always done in p
312d0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e lace and do.** n
312e0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 ot invalidate a
312f0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 prior pointer, t
31300 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 hough of course
31310 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
31320 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 he buffer.** tha
31330 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e t the prior poin
31340 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 ter references w
31350 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f ill have been mo
31360 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b dified. Other k
31370 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 inds.** of conve
31380 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 rsion are done i
31390 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 n place when it
313a0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 is possible, but
313b0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a sometimes they.
313c0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 ** are not possi
313d0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
313e0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
313f0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
31400 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dated..**.** The
31410 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 safest and easi
31420 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 est to remember
31430 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 policy is to inv
31440 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e oke these routin
31450 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 es.** in one of
31460 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 the following wa
31470 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ys:.**.** <ul>.*
31480 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
31490 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c olumn_text() fol
314a0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
314b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
314c0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
314d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
314e0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
314f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31500 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c tes()</li>.** <
31510 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
31520 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f n_text16() follo
31530 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
31540 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c olumn_bytes16()<
31550 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a /li>.** </ul>.**
31560 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
31570 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 ds, you should c
31580 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 all sqlite3_colu
31590 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 mn_text(),.** sq
315a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
315b0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f b(), or sqlite3_
315c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
315d0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 first to force t
315e0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 he result.** int
315f0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f o the desired fo
31600 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b rmat, then invok
31610 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31620 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 _bytes() or.** s
31630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31640 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 tes16() to find
31650 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
31660 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 result. Do not
31670 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 mix calls.** to
31680 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31690 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
316a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 _column_blob() w
316b0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ith calls to.**
316c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
316d0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f ytes16(), and do
316e0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 not mix calls t
316f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
31700 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 _text16().** wit
31710 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
31720 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
31730 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f )..**.** ^The po
31740 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
31750 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 are valid until
31760 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
31770 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 n occurs as.** d
31780 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 escribed above,
31790 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 or until [sqlite
317a0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
317b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
317c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
317d0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c nalize()] is cal
317e0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 led. ^The memor
317f0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 y space used to
31800 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 hold strings.**
31810 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 and BLOBs is fre
31820 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
31830 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e . Do <b>not</b>
31840 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
31850 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b rs returned.** [
31860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
31870 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
31880 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
31890 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
318a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
318b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
318c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
318d0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
318e0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
318f0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
31900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
31910 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
31920 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
31930 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
31940 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
31950 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
31960 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
31970 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
31980 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
31990 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
319a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
319b0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
319c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
319d0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c NOMEM].)^.*/.SQL
319e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
319f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
31a00 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f mn_blob(sqlite3_
31a10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
31a20 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
31a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31a40 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 bytes(sqlite3_st
31a50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
31a60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
31a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31a80 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 tes16(sqlite3_st
31a90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
31aa0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c SQLITE_API doubl
31ab0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31ac0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
31ad0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
31ae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
31af0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31b00 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
31b10 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
31b20 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
31b30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 _int64 sqlite3_c
31b40 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 olumn_int64(sqli
31b50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
31b60 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
31b70 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 const unsigned
31b80 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
31b90 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
31ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
31bb0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 l);.SQLITE_API c
31bc0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
31bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
31be0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
31bf0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
31c00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
31c10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
31c20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
31c30 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
31c40 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 PI sqlite3_value
31c50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
31c60 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
31c70 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31c80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31c90 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
31ca0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
31cb0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
31cc0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
31cd0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
31ce0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
31cf0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
31d00 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
31d10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
31d20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
31d30 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
31d40 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
31d50 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
31d60 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
31d70 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
31d80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
31d90 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
31da0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
31db0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
31dc0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
31dd0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
31de0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
31df0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
31e00 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
31e10 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
31e20 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
31e30 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
31e40 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
31e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
31e60 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
31e70 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
31e80 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
31e90 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
31ea0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
31eb0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
31ec0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
31ed0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
31ee0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
31ef0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
31f00 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
31f10 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
31f20 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
31f30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
31f40 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
31f50 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
31f60 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
31f70 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
31f80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
31f90 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
31fa0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
31fb0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
31fc0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
31fd0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
31fe0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
31ff0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
32000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
32010 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
32020 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
32030 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
32040 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
32050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
32060 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
32070 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
32080 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
32090 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
320a0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
320b0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
320c0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
320d0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
320e0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
320f0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
32100 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
32110 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
32120 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
32130 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
32140 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
32150 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
32160 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
32170 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
32180 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 I3REF: Reset A P
32190 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
321a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 t Object.**.** T
321b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 he sqlite3_reset
321c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
321d0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 alled to reset a
321e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
321f0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 ment].** object
32200 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
32210 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 ial state, ready
32220 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 to be re-execut
32230 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 ed..** ^Any SQL
32240 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 statement variab
32250 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c les that had val
32260 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 ues bound to the
32270 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b m using.** the [
32280 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
32290 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 b | sqlite3_bind
322a0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e _*() API] retain
322b0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a their values..*
322c0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 * Use [sqlite3_c
322d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d lear_bindings()]
322e0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 to reset the bi
322f0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ndings..**.** ^T
32300 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
32310 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(S)] interface
32320 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 resets the [prep
32330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
32340 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 S.** back to the
32350 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 beginning of it
32360 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a s program..**.**
32370 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
32380 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cent call to [sq
32390 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 lite3_step(S)] f
323a0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 or the.** [prepa
323b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
323c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
323d0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 E_ROW] or [SQLIT
323e0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 E_DONE],.** or i
323f0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
32400 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 S)] has never be
32410 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 fore been called
32420 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b on S,.** then [
32430 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
32440 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ] returns [SQLIT
32450 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 E_OK]..**.** ^If
32460 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
32470 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
32480 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 3_step(S)] for t
32490 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
324a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 statement] S ind
324b0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c icated an error,
324c0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 then.** [sqlite
324d0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 3_reset(S)] retu
324e0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 rns an appropria
324f0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e te [error code].
32500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
32510 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
32520 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f nterface does no
32530 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
32540 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 ues.** of any [s
32550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
32560 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 |bindings] on th
32570 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
32580 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c ement] S..*/.SQL
32590 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
325a0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 te3_reset(sqlite
325b0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
325c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
325d0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 Create Or Redef
325e0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e ine SQL Function
325f0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
32600 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
32610 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b n routines}.** K
32620 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
32630 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
32640 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b L function}.** K
32650 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 EYWORDS: {applic
32660 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
32670 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a L functions}.**.
32680 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
32690 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c ons (collectivel
326a0 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 y known as "func
326b0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f tion creation ro
326c0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 utines").** are
326d0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 used to add SQL
326e0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
326f0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 regates or to re
32700 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 define the behav
32710 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 ior.** of existi
32720 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ng SQL functions
32730 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 or aggregates.
32740 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 The only differ
32750 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a ences between.**
32760 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
32770 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 are the text enc
32780 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 oding expected f
32790 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 or.** the second
327a0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 parameter (the
327b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 name of the func
327c0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 tion being creat
327d0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 ed).** and the p
327e0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e resence or absen
327f0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 ce of a destruct
32800 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a or callback for.
32810 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
32820 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
32830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
32840 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
32850 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
32860 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 nection] to whic
32870 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e h the SQL.** fun
32880 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 ction is to be a
32890 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 dded. ^If an ap
328a0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d plication uses m
328b0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
328c0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
328d0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 ion then applica
328e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
328f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 functions must
32900 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 be added.** to e
32910 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
32920 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 nection separate
32930 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
32940 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
32950 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
32960 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
32970 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 to be created or
32980 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 .** redefined.
32990 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 ^The length of t
329a0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 he name is limit
329b0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 ed to 255 bytes
329c0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 in a UTF-8.** re
329d0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 presentation, ex
329e0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a clusive of the z
329f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero-terminator.
32a00 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
32a10 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c name.** length l
32a20 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 imit is in UTF-8
32a30 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 bytes, not char
32a40 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 acters nor UTF-1
32a50 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6 bytes. .** ^A
32a60 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 ny attempt to cr
32a70 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 eate a function
32a80 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 with a longer na
32a90 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c me.** will resul
32aa0 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 t in [SQLITE_MIS
32ab0 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 USE] being retur
32ac0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
32ad0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
32ae0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 (nArg).** is the
32af0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
32b00 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 ents that the SQ
32b10 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
32b20 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 aggregate takes
32b30 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d . ^If this param
32b40 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eter is -1, then
32b50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32b60 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
32b70 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e e may take any n
32b80 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
32b90 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ts between 0 and
32ba0 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 the limit.** se
32bb0 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 t by [sqlite3_li
32bc0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d mit]([SQLITE_LIM
32bd0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d IT_FUNCTION_ARG]
32be0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 ). If the third
32bf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 .** parameter is
32c00 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 less than -1 or
32c10 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 greater than 12
32c20 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 7 then the behav
32c30 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 ior is.** undefi
32c40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
32c50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
32c60 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 , eTextRep, spec
32c70 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 ifies what.** [S
32c80 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 QLITE_UTF8 | tex
32c90 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 t encoding] this
32ca0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 SQL function pr
32cb0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 efers for.** its
32cc0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 parameters. Ev
32cd0 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ery SQL function
32ce0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32cf0 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 must be able to
32d00 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 work.** with UTF
32d10 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 -8, UTF-16le, or
32d20 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 UTF-16be. But
32d30 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 some implementat
32d40 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d ions may be.** m
32d50 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 ore efficient wi
32d60 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 th one encoding
32d70 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e than another. ^
32d80 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d An application m
32d90 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c ay.** invoke sql
32da0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
32db0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 tion() or sqlite
32dc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
32dd0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a n16() multiple.*
32de0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 * times with the
32df0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 same function b
32e00 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e ut with differen
32e10 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 t values of eTex
32e20 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d tRep..** ^When m
32e30 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
32e40 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
32e50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
32e60 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
32e70 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
32e80 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
32e90 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
32ea0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
32eb0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 onversion..** If
32ec0 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 there is only a
32ed0 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e single implemen
32ee0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 tation which doe
32ef0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 s not care what
32f00 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 text.** encoding
32f10 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 is used, then t
32f20 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
32f30 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 nt should be [SQ
32f40 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a LITE_ANY]..**.**
32f50 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 ^(The fifth par
32f60 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 ameter is an arb
32f70 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 itrary pointer.
32f80 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
32f90 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 ion of the.** fu
32fa0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 nction can gain
32fb0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 access to this p
32fc0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 ointer using [sq
32fd0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
32fe0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 )].)^.**.** ^The
32ff0 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 sixth, seventh
33000 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d and eighth param
33010 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
33020 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
33030 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
33040 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
33050 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
33060 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
33070 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
33080 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c gregate. ^A scal
33090 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ar SQL function
330a0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
330b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
330c0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 e xFunc.** callb
330d0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 ack only; NULL p
330e0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 ointers must be
330f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 passed as the xS
33100 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a tep and xFinal.*
33110 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 * parameters. ^A
33120 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
33130 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
33140 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
33150 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 ion of xStep.**
33160 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
33170 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 ULL pointer must
33180 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 be passed for x
33190 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 Func. ^To delete
331a0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 an existing.**
331b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 SQL function or
331c0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 aggregate, pass
331d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f NULL pointers fo
331e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
331f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
33200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 s..**.** ^(If th
33210 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 e ninth paramete
33220 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
33230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
33240 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a ) is not NULL,.*
33250 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 * then it is des
33260 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 tructor for the
33270 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
33280 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 pointer. .** Th
33290 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
332a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 invoked when the
332b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c function is del
332c0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 eted, either by
332d0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 being.** overloa
332e0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 ded or when the
332f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33300 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a ion closes.)^.**
33310 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
33320 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 is also invoked
33330 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a if the call to.
33340 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ** sqlite3_creat
33350 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
33360 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 fails..** ^When
33370 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 the destructor c
33380 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 allback of the t
33390 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 enth parameter i
333a0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a s invoked, it.**
333b0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e is passed a sin
333c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
333d0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ch is a copy of
333e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
333f0 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 data .** pointer
33400 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 which was the f
33410 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 ifth parameter t
33420 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
33430 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a _function_v2()..
33440 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 **.** ^It is per
33450 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 mitted to regist
33460 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c er multiple impl
33470 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
33480 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 he same.** funct
33490 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 ions with the sa
334a0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 me name but with
334b0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e either differin
334c0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 g numbers of.**
334d0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 arguments or dif
334e0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 fering preferred
334f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e text encodings.
33500 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 ^SQLite will u
33510 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
33520 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f entation that mo
33530 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 st closely match
33540 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 es the way in wh
33550 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 ich the.** SQL f
33560 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e unction is used.
33570 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d ^A function im
33580 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
33590 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 h a non-negative
335a0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 .** nArg paramet
335b0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d er is a better m
335c0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
335d0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
335e0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 ion with.** a ne
335f0 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 gative nArg. ^A
33600 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
33610 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 the preferred te
33620 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d xt encoding.** m
33630 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 atches the datab
33640 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ase encoding is
33650 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 a better.** matc
33660 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
33670 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
33680 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
33690 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 t. .** ^A funct
336a0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
336b0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
336c0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 e is between UTF
336d0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 16le and UTF16be
336e0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 .** is a closer
336f0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
33700 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
33710 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
33720 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 nce is.** betwee
33730 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 n UTF8 and UTF16
33740 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 ..**.** ^Built-i
33750 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 n functions may
33760 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 be overloaded by
33770 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
33780 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
33790 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 ns..**.** ^An ap
337a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
337b0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 d function is pe
337c0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 rmitted to call
337d0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
337e0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 interfaces. How
337f0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 ever, such calls
33800 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f must not.** clo
33810 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
33820 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 connection nor f
33830 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 inalize or reset
33840 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a the prepared.**
33850 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 statement in wh
33860 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ich the function
33870 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
33880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
33890 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
338a0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
338b0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
338c0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
338d0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
338e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
338f0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
33900 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
33910 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33920 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33930 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
33940 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
33950 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
33960 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
33970 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
33980 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
33990 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
339a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
339b0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 function16(. sq
339c0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
339d0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 st void *zFuncti
339e0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
339f0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
33a00 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
33a10 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
33a20 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
33a30 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
33a40 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
33a50 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
33a60 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
33a70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
33a80 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
33a90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33aa0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
33ab0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
33ac0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
33ad0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
33ae0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
33af0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
33b00 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
33b10 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
33b20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
33b30 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
33b40 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
33b50 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
33b60 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
33b70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33b80 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33b90 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
33ba0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
33bb0 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 ntext*),. void(
33bc0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a *xDestroy)(void*
33bd0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
33be0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
33bf0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ings.**.** These
33c00 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
33c10 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
33c20 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
33c30 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
33c40 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
33c50 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
33c60 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
33c70 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
33c80 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
33c90 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
33ca0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
33cb0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
33cc0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
33cd0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
33ce0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
33cf0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
33d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
33d10 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
33d20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
33d30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
33d40 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
33d50 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
33d60 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
33d70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
33d80 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
33d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33da0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
33db0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
33dc0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
33dd0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
33de0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
33df0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
33e00 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
33e10 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
33e20 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
33e30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
33e40 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
33e50 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
33e60 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
33e70 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
33e80 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
33e90 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
33ea0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
33eb0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
33ec0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
33ed0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
33ee0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
33ef0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
33f00 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
33f10 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
33f20 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
33f30 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
33f40 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
33f50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
33f60 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f count(sqlite3_co
33f70 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
33f80 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
33f90 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
33fa0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 3_expired(sqlite
33fb0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 3_stmt*);.SQLITE
33fc0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
33fd0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
33fe0 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 e3_transfer_bind
33ff0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
34000 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 t*, sqlite3_stmt
34010 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
34020 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
34030 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f int sqlite3_glo
34040 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
34050 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
34060 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
34070 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 void sqlite3_thr
34080 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 ead_cleanup(void
34090 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
340a0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
340b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f int sqlite3_memo
340c0 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 ry_alarm(void(*)
340d0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 (void*,sqlite3_i
340e0 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c nt64,int),void*,
340f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
34100 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
34110 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
34120 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
34130 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a arameter Values.
34140 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
34150 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
34160 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
34170 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
34180 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
34190 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
341a0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
341b0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
341c0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
341d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
341e0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
341f0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
34200 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
34210 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
34220 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
34230 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
34240 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
34250 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
34260 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
34270 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
34280 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
34290 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
342a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
342b0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
342c0 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d ** The 3rd param
342d0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
342e0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
342f0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
34300 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 to.** [protected
34310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34320 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 objects. There
34330 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f is one [sqlite3_
34340 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f value] object fo
34350 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 r.** each parame
34360 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 ter to the SQL f
34370 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 unction. These
34380 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
34390 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 d to.** extract
343a0 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 values from the
343b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
343c0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 objects..**.** T
343d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
343e0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 rk only with [pr
343f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
34400 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a value] objects..
34410 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
34420 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 o use these rout
34430 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 ines on an [unpr
34440 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
34450 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 value].** object
34460 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
34470 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a fined behavior..
34480 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
34490 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 tines work just
344a0 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 like the corresp
344b0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 onding [column a
344c0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
344d0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
344e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
344f0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 take a single [p
34500 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
34510 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a _value] object.*
34520 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 * pointer instea
34530 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f d of a [sqlite3_
34540 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 stmt*] pointer a
34550 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f nd an integer co
34560 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a lumn number..**.
34570 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34580 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 value_text16() i
34590 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 nterface extract
345a0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
345b0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 g.** in the nati
345c0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 ve byte-order of
345d0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e the host machin
345e0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 e. ^The.** sqli
345f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34600 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 be() and sqlite3
34610 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
34620 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
34630 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 extract UTF-16 s
34640 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
34650 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
34660 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
34670 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ely..**.** ^(The
34680 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
34690 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e umeric_type() in
346a0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
346b0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d to apply.** num
346c0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f eric affinity to
346d0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 the value. Thi
346e0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 s means that an
346f0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 attempt is.** ma
34700 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 de to convert th
34710 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e e value to an in
34720 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e teger or floatin
34730 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 g point. If.**
34740 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f such a conversio
34750 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 n is possible wi
34760 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e thout loss of in
34770 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 formation (in ot
34780 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 her.** words, if
34790 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 the value is a
347a0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b string that look
347b0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 s like a number)
347c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e .** then the con
347d0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f version is perfo
347e0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rmed. Otherwise
347f0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f no conversion o
34800 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 ccurs..** The [S
34810 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
34820 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 datatype] after
34830 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 conversion is re
34840 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 turned.)^.**.**
34850 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 Please pay parti
34860 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 cular attention
34870 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 to the fact that
34880 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 the pointer ret
34890 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
348a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
348b0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 b()], [sqlite3_v
348c0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 alue_text()], or
348d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
348e0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e ue_text16()] can
348f0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 be invalidated
34900 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 by a subsequent
34910 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
34920 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
34930 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
34940 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b ue_bytes16()], [
34950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
34960 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
34970 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
34980 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 16()]..**.** The
34990 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
349a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
349b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
349c0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 as.** the SQL fu
349d0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 nction that supp
349e0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 lied the [sqlite
349f0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 3_value*] parame
34a00 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ters..*/.SQLITE_
34a10 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
34a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
34a30 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ob(sqlite3_value
34a40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
34a50 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
34a60 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
34a70 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
34a80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
34a90 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c alue_bytes16(sql
34aa0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
34ab0 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 LITE_API double
34ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f sqlite3_value_do
34ad0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c uble(sqlite3_val
34ae0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34af0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
34b00 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
34b10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
34b20 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
34b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
34b40 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c nt64(sqlite3_val
34b50 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34b60 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 const unsigned
34b70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 char *sqlite3_va
34b80 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
34b90 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34ba0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
34bb0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
34bc0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
34bd0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
34be0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
34bf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
34c00 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16le(sqlite3_val
34c10 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
34c20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
34c30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
34c40 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
34c50 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
34c60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
34c70 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 e_type(sqlite3_v
34c80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
34c90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 PI int sqlite3_v
34ca0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
34cb0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
34cc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34cd0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 EF: Obtain Aggre
34ce0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f gate Function Co
34cf0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c ntext.**.** Impl
34d00 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 ementations of a
34d10 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
34d20 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a ctions use this.
34d30 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c ** routine to al
34d40 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f locate memory fo
34d50 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
34d60 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 state..**.** ^Th
34d70 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 e first time the
34d80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
34d90 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
34da0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
34db0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 d .** for a part
34dc0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 icular aggregate
34dd0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 function, SQLit
34de0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e e.** allocates N
34df0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
34e00 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f es out that memo
34e10 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ry, and returns
34e20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
34e30 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 the new memory.
34e40 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 ^On second and s
34e50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
34e60 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 to.** sqlite3_ag
34e70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
34e80 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 ) for the same a
34e90 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
34ea0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 n instance,.** t
34eb0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
34ec0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c s returned. Sql
34ed0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34ee0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d ontext() is norm
34ef0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f ally.** called o
34f00 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 nce for each inv
34f10 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ocation of the x
34f20 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e Step callback an
34f30 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 d then one.** la
34f40 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 st time when the
34f50 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
34f60 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 is invoked. ^(
34f70 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 When no rows mat
34f80 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 ch.** an aggrega
34f90 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 te query, the xS
34fa0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f tep() callback o
34fb0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
34fc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c function.** impl
34fd0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 ementation is ne
34fe0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 ver called and x
34ff0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 Final() is calle
35000 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a d exactly once..
35010 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 ** In those case
35020 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 s, sqlite3_aggre
35030 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d gate_context() m
35040 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 ight be called f
35050 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 or the.** first
35060 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e time from within
35070 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a xFinal().)^.**.
35080 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35090 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
350a0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 t(C,N) routine r
350b0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
350c0 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a inter if N is.**
350d0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 less than or eq
350e0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 ual to zero or i
350f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
35100 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ate error occurs
35110 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d ..**.** ^(The am
35120 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c ount of space al
35130 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
35140 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35150 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 text(C,N) is.**
35160 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 determined by th
35170 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e e N parameter on
35180 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 first successfu
35190 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e l call. Changin
351a0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f g the.** value o
351b0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e f N in subsequen
351c0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
351d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
351e0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 ext() within.**
351f0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
35200 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
35210 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 ance will not re
35220 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a size the memory.
35230 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e ** allocation.)^
35240 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 .**.** ^SQLite a
35250 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
35260 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
35270 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 located by .** s
35280 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
35290 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 _context() when
352a0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 the aggregate qu
352b0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a ery concludes..*
352c0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
352d0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 arameter must be
352e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
352f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
35300 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f xt | SQL functio
35310 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 n context] that
35320 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
35330 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
35340 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c xStep or xFinal
35350 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
35360 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 e that implement
35370 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a s the aggregate.
35380 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ** function..**.
35390 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
353a0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
353b0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
353c0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
353d0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
353e0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
353f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
35400 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
35410 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35420 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
35430 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
35440 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
35450 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
35460 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a or Functions.**.
35470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35480 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 user_data() inte
35490 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
354a0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
354b0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 ointer that was
354c0 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 the pUserData pa
354d0 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 rameter (the 5th
354e0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
354f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
35500 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
35510 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
35520 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35530 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
35540 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
35550 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
35560 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
35570 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
35580 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
35590 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
355a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
355b0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
355c0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
355d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
355e0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
355f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
35600 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 id *sqlite3_user
35610 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f _data(sqlite3_co
35620 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
35630 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
35640 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f se Connection Fo
35650 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a r Functions.**.*
35660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
35670 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
35680 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
35690 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
356a0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f * the pointer to
356b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
356c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 onnection] (the
356d0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 1st parameter).*
356e0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
356f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35700 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
35710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
35720 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
35730 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
35740 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
35750 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
35760 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
35770 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
35780 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 sqlite3 *sqlite
35790 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
357a0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
357b0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
357c0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
357d0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a Auxiliary Data.
357e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 **.** The follow
357f0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e ing two function
35800 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
35810 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
35820 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f tions to.** asso
35830 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 ciate metadata w
35840 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
35850 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
35860 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
35870 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
35880 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
35890 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
358a0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
358b0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
358c0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
358d0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
358e0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 ociated metadata
358f0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
35900 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
35910 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
35920 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
35930 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
35940 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
35950 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
35960 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
35970 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
35980 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
35990 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
359a0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
359b0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 with the SQL va
359c0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
359d0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
359e0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e sion.** pattern.
359f0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 The compiled r
35a00 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
35a10 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 n can be reused
35a20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 on multiple.** i
35a30 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
35a40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
35a50 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 so that the orig
35a60 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 inal pattern str
35a70 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ing.** does not
35a80 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d need to be recom
35a90 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e piled on each in
35aa0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 vocation..**.**
35ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
35ac0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
35ad0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
35ae0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
35af0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
35b00 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 ated by the sqli
35b10 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
35b20 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 ) function with
35b30 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
35b40 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 .** value to the
35b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35b60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e ined function. ^
35b70 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 If no metadata h
35b80 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 as been ever.**
35b90 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
35ba0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 Nth argument of
35bb0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f the function, o
35bc0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 r if the corresp
35bd0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 onding.** functi
35be0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 on parameter has
35bf0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 changed since t
35c00 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 he meta-data was
35c10 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 set,.** then sq
35c20 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
35c30 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 a() returns a NU
35c40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
35c50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
35c60 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
35c70 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 erface saves the
35c80 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 metadata.** poi
35c90 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 nted to by its 3
35ca0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 rd parameter as
35cb0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 the metadata for
35cc0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 the N-th.** arg
35cd0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 ument of the app
35ce0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35cf0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 function. Subs
35d00 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
35d10 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 to sqlite3_get_a
35d20 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 uxdata() might r
35d30 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c eturn this data,
35d40 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f if it has.** no
35d50 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 t been destroyed
35d60 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e ..** ^If it is n
35d70 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 ot NULL, SQLite
35d80 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 will invoke the
35d90 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 destructor.** fu
35da0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 nction given by
35db0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
35dc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 r to sqlite3_set
35dd0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a _auxdata() on.**
35de0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 the metadata wh
35df0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
35e00 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 ding function pa
35e10 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a rameter changes.
35e20 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 ** or when the S
35e30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
35e40 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 pletes, whicheve
35e50 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
35e60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 *.** SQLite is f
35e70 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 ree to call the
35e80 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 destructor and d
35e90 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 rop metadata on
35ea0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 any.** parameter
35eb0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e of any function
35ec0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e at any time. ^
35ed0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 The only guarant
35ee0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 ee is that.** th
35ef0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c e destructor wil
35f00 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f l be called befo
35f10 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 re the metadata
35f20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a is dropped..**.*
35f30 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c * ^(In practice,
35f40 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 metadata is pre
35f50 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
35f60 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
35f70 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
35f80 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
35f90 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
35fa0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
35fb0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
35fc0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 ues and [paramet
35fd0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ers].)^.**.** Th
35fe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
35ff0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
36000 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
36010 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
36020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
36030 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
36040 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
36050 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
36060 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
36070 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 t*, int N);.SQLI
36080 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
36090 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
360a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
360b0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 , int N, void*,
360c0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 void (*)(void*))
360d0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
360e0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 EF: Constants De
360f0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 fining Special D
36100 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 estructor Behavi
36110 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 or.**.** These a
36120 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 re special value
36130 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 s for the destru
36140 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 ctor that is pas
36150 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a sed in as the.**
36160 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 final argument
36170 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 to routines like
36180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
36190 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 _blob()]. ^If t
361a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
361b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c argument is SQL
361c0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d ITE_STATIC, it m
361d0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
361e0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 ntent pointer is
361f0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 constant.** and
36200 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e will never chan
36210 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 ge. It does not
36220 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 need to be dest
36230 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 royed. ^The.**
36240 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
36250 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 value means tha
36260 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 t the content wi
36270 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 ll likely change
36280 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 in.** the near
36290 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 future and that
362a0 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 SQLite should ma
362b0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 ke its own priva
362c0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 te copy of.** th
362d0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 e content before
362e0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
362f0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 * The typedef is
36300 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f necessary to wo
36310 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 rk around proble
36320 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a ms in certain.**
36330 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 C++ compilers.
36340 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 See ticket #219
36350 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 1..*/.typedef vo
36360 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 id (*sqlite3_des
36370 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f tructor_type)(vo
36380 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 id*);.#define SQ
36390 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 LITE_STATIC
363a0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
363b0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 uctor_type)0).#d
363c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
363d0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 NSIENT ((sqlit
363e0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
363f0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 pe)-1)../*.** CA
36400 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 PI3REF: Setting
36410 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e The Result Of An
36420 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a SQL Function.**
36430 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
36440 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 es are used by t
36450 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e he xFunc or xFin
36460 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 al callbacks tha
36470 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 t.** implement S
36480 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
36490 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 aggregates. Se
364a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 e.** [sqlite3_cr
364b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
364c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
364d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
364e0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 )].** for additi
364f0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
36500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 ..**.** These fu
36510 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 nctions work ver
36520 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 y much like the
36530 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 [parameter bindi
36540 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a ng] family of.**
36550 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 functions used
36560 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 to bind values t
36570 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 o host parameter
36580 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 s in prepared st
36590 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 atements..** Ref
365a0 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 er to the [SQL p
365b0 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 arameter] docume
365c0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
365d0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
365e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 on..**.** ^The s
365f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
36600 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ob() interface s
36610 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
36620 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
36630 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
36640 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
36650 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 BLOB whose cont
36660 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a ent is pointed.*
36670 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f * to by the seco
36680 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 nd parameter and
36690 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 which is N byte
366a0 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 s long where N i
366b0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 s the.** third p
366c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
366d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
366e0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 ult_zeroblob() i
366f0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 nterfaces set th
36700 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
36710 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36720 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36730 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e to be a BLOB con
36740 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f taining all zero
36750 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 .** bytes and N
36760 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 bytes in size, w
36770 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 here N is the va
36780 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 lue of the 2nd p
36790 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
367a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
367b0 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 ult_double() int
367c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
367d0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
367e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
367f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
36800 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 o be a floating
36810 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 point value spec
36820 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 ified.** by its
36830 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
36840 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36850 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
36860 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
36870 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e lt_error16() fun
36880 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 ctions.** cause
36890 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 the implemented
368a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
368b0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 throw an excepti
368c0 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 on..** ^SQLite u
368d0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 ses the string p
368e0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
368f0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 .** 2nd paramete
36900 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 r of sqlite3_res
36910 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 ult_error() or s
36920 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36930 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 ror16().** as th
36940 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 e text of an err
36950 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 or message. ^SQ
36960 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 Lite interprets
36970 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
36980 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d sage string from
36990 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
369a0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 error() as UTF-8
369b0 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 . ^SQLite.** int
369c0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 erprets the stri
369d0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ng from sqlite3_
369e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
369f0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 as UTF-16 in na
36a00 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 tive.** byte ord
36a10 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 er. ^If the thi
36a20 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
36a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36a40 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
36a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36a60 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 r16() is negativ
36a70 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 e then SQLite ta
36a80 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 kes as the error
36a90 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 .** message all
36aa0 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 text up through
36ab0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
36ac0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 haracter..** ^If
36ad0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
36ae0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
36af0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
36b00 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 r.** sqlite3_res
36b10 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
36b20 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 non-negative th
36b30 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
36b40 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 that many.** byt
36b50 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
36b60 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 rs) from the 2nd
36b70 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
36b80 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
36b90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
36ba0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
36bb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
36bc0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
36bd0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 routines make a
36be0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
36bf0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
36c00 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a e text before.**
36c10 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 they return. H
36c20 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e ence, the callin
36c30 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 g function can d
36c40 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 eallocate or.**
36c50 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 modify the text
36c60 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 after they retur
36c70 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a n without harm..
36c80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36c90 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
36ca0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 e() function cha
36cb0 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 nges the error c
36cc0 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 ode.** returned
36cd0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 by SQLite as a r
36ce0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f esult of an erro
36cf0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e r in a function.
36d00 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a ^By default,.*
36d10 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 * the error code
36d20 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 is SQLITE_ERROR
36d30 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 . ^A subsequent
36d40 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
36d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
36d60 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
36d70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 sult_error16() r
36d80 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 esets the error
36d90 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 code to SQLITE_E
36da0 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 RROR..**.** ^The
36db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36dc0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 error_toobig() i
36dd0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
36de0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
36df0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 an.** error indi
36e00 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
36e10 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
36e20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 too long to repr
36e30 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 esent..**.** ^Th
36e40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36e50 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 _error_nomem() i
36e60 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
36e70 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
36e80 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 an.** error indi
36e90 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
36ea0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
36eb0 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 failed..**.** ^T
36ec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36ed0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 t_int() interfac
36ee0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
36ef0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
36f00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
36f10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
36f20 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 o be the 32-bit
36f30 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
36f40 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
36f50 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
36f60 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 t..** ^The sqlit
36f70 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
36f80 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
36f90 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
36fa0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c e.** of the appl
36fb0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
36fc0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
36fd0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 he 64-bit signed
36fe0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 integer.** valu
36ff0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 e given in the 2
37000 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
37010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37020 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e result_null() in
37030 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
37040 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a return value.**
37050 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
37060 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37070 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e tion to be NULL.
37080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 te3_result_text(
370a0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ), sqlite3_resul
370b0 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 t_text16(),.** s
370c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
370d0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 xt16le(), and sq
370e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
370f0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 t16be() interfac
37100 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 es.** set the re
37110 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
37120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
37130 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
37140 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 o be.** a text s
37150 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 tring which is r
37160 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 epresented as UT
37170 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 F-8, UTF-16 nati
37180 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a ve byte order,.*
37190 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 * UTF-16 little
371a0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 endian, or UTF-1
371b0 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 6 big endian, re
371c0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e spectively..** ^
371d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 SQLite takes the
371e0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f text result fro
371f0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f m the applicatio
37200 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e n from.** the 2n
37210 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 d parameter of t
37220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37230 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
37240 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 es..** ^If the 3
37250 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
37260 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
37270 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
37280 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 ces.** is negati
37290 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ve, then SQLite
372a0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 takes result tex
372b0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 t from the 2nd p
372c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f arameter.** thro
372d0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
372e0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
372f0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 ^If the 3rd par
37300 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
37310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37320 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
37330 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
37340 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 , then as many b
37350 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
37360 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 ters) of the tex
37370 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 t.** pointed to
37380 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
37390 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 eter are taken a
373a0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f s the applicatio
373b0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e n-defined.** fun
373c0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 ction result. I
373d0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
373e0 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 ter is non-negat
373f0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 ive, then it.**
37400 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 must be the byte
37410 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 offset into the
37420 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 string where th
37430 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 e NUL terminator
37440 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 would.** appear
37450 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 if the string w
37460 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 here NUL termina
37470 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c ted. If any NUL
37480 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 characters occu
37490 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 r.** in the stri
374a0 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 ng at a byte off
374b0 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 set that is less
374c0 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 than the value
374d0 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 of the 3rd.** pa
374e0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 rameter, then th
374f0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
37500 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 ng will contain
37510 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e embedded NULs an
37520 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 d the.** result
37530 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f of expressions o
37540 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 perating on stri
37550 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 ngs with embedde
37560 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 d NULs is undefi
37570 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ned..** ^If the
37580 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
37590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
375a0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
375b0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 aces.** or sqlit
375c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 e3_result_blob i
375d0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 s a non-NULL poi
375e0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
375f0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 e calls that.**
37600 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 function as the
37610 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 destructor on th
37620 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
37630 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 esult when it ha
37640 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 s.** finished us
37650 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e ing that result.
37660 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
37670 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
37680 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37690 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
376a0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 or to.** sqlite
376b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
376c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
376d0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 stant SQLITE_STA
376e0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 TIC, then SQLite
376f0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 .** assumes that
37700 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f the text or BLO
37710 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 B result is in c
37720 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e onstant space an
37730 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f d does not.** co
37740 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f py the content o
37750 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
37760 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 nor call a destr
37770 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e uctor on the con
37780 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 tent.** when it
37790 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
377a0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
377b0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
377c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
377d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
377e0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
377f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
37800 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
37810 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
37820 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 t SQLITE_TRANSIE
37830 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 NT.** then SQLit
37840 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
37850 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 f the result int
37860 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 o space obtained
37870 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 from.** from [s
37880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
37890 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 before it retur
378a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
378b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
378c0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 lue() interface
378d0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
378e0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
378f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
37900 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 nction to be a c
37910 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 opy the.** [unpr
37920 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
37930 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 value] object sp
37940 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 ecified by the 2
37950 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e nd parameter. ^
37960 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 The.** sqlite3_r
37970 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
37980 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
37990 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
379a0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 ite3_value].** s
379b0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 o that the [sqli
379c0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 te3_value] speci
379d0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 fied in the para
379e0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 meter may change
379f0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f or.** be deallo
37a00 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 cated after sqli
37a10 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
37a20 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f () returns witho
37a30 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b ut harm..** ^A [
37a40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
37a50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
37a60 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 may always be us
37a70 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b ed where an.** [
37a80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
37a90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
37aa0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 t is required, s
37ab0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 o either.** kind
37ac0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
37ad0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 ue] object can b
37ae0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 e used with this
37af0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
37b00 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 * If these routi
37b10 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 nes are called f
37b20 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 rom within the d
37b30 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a ifferent thread.
37b40 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
37b50 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
37b60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
37b70 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
37b80 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 received.** the
37b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
37ba0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
37bb0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
37bc0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 fined..*/.SQLITE
37bd0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
37be0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
37bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37c00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
37c10 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
37c20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
37c30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37c40 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 t_double(sqlite3
37c50 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c _context*, doubl
37c60 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 e);.SQLITE_API v
37c70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
37c80 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 lt_error(sqlite3
37c90 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
37ca0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 char*, int);.SQ
37cb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
37cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37cd0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
37ce0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
37cf0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
37d00 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
37d10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
37d20 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f oobig(sqlite3_co
37d30 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
37d40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
37d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
37d60 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
37d70 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
37d80 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
37d90 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
37da0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37db0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
37dc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
37dd0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
37de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
37df0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 t);.SQLITE_API v
37e00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
37e10 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 lt_int64(sqlite3
37e20 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
37e30 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 e3_int64);.SQLIT
37e40 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
37e50 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 e3_result_null(s
37e60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
37e70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
37e80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37e90 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
37ea0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
37eb0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
37ec0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
37ed0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
37ee0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37ef0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37f00 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
37f10 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
37f20 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
37f30 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
37f40 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 sult_text16le(sq
37f50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
37f60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
37f70 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
37f80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
37f90 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37fa0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
37fb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
37fc0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
37fd0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
37fe0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
37ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
38000 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
38010 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
38020 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
38030 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
38040 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 sult_zeroblob(sq
38050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
38060 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
38070 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 API3REF: Define
38080 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 New Collating Se
38090 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 quences.**.** ^T
380a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
380b0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d dd, remove, or m
380c0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 odify a [collati
380d0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a on] associated.*
380e0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 * with the [data
380f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
38100 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 specified as th
38110 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
38120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
38130 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 e of the collati
38140 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 on is a UTF-8 st
38150 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
38160 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
38170 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
38180 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
38190 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
381a0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
381b0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
381c0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 rder for sqlite3
381d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
381e0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 n16()..** ^Colla
381f0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 tion names that
38200 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 compare equal ac
38210 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 cording to [sqli
38220 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 te3_strnicmp()]
38230 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 are.** considere
38240 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 d to be the same
38250 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 name..**.** ^(T
38260 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
38270 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 t (eTextRep) mus
38280 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 t be one of the
38290 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 constants:.** <u
382a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
382b0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 TE_UTF8],.** <li
382c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c > [SQLITE_UTF16L
382d0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c E],.** <li> [SQL
382e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
382f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
38300 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e F16], or.** <li>
38310 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 [SQLITE_UTF16_A
38320 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c LIGNED]..** </ul
38330 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 >)^.** ^The eTex
38340 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 tRep argument de
38350 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 termines the enc
38360 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 oding of strings
38370 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 passed.** to th
38380 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
38390 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 tion callback, x
383a0 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 Callback..** ^Th
383b0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d e [SQLITE_UTF16]
383c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 and [SQLITE_UTF
383d0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 16_ALIGNED] valu
383e0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a es for eTextRep.
383f0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 ** force strings
38400 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 to be UTF16 wit
38410 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 h native byte or
38420 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 der..** ^The [SQ
38430 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
38440 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 ED] value for eT
38450 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 extRep forces st
38460 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a rings to begin.*
38470 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 * on an even byt
38480 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a e address..**.**
38490 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 ^The fourth arg
384a0 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 ument, pArg, is
384b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
384c0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ata pointer that
384d0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 is passed.** th
384e0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
384f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
38500 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
38510 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a ction callback..
38520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 **.** ^The fifth
38530 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c argument, xCall
38540 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 back, is a point
38550 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 er to the collat
38560 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ing function..**
38570 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 ^Multiple colla
38580 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 ting functions c
38590 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
385a0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
385b0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 name but.** with
385c0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 different eText
385d0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 Rep parameters a
385e0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 nd SQLite will u
385f0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 se whichever.**
38600 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
38610 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
38620 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 nt of data trans
38630 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 formation..** ^I
38640 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 f the xCallback
38650 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c argument is NULL
38660 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 then the collat
38670 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a ing function is.
38680 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 ** deleted. ^Wh
38690 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 en all collating
386a0 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e functions havin
386b0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 g the same name
386c0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 are deleted,.**
386d0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 that collation i
386e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 s no longer usab
386f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 le..**.** ^The c
38700 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
38710 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e n callback is in
38720 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 voked with a cop
38730 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a y of the pArg .*
38740 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 * application da
38750 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 ta pointer and w
38760 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 ith two strings
38770 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 in the encoding
38780 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
38790 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 the eTextRep arg
387a0 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c ument. The coll
387b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d ating functio