0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 36 2e 20 20 ersion 3.7.16.
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 36 22 0a "3.7.16".
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 36 0a 23 64 65 66 69 6e 65 20 53 51 07016.#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 33 2d 30 31 2d 31 37 20 "2013-01-17
5db0: 30 33 3a 31 38 3a 33 38 20 36 35 32 32 33 33 64 03:18:38 652233d
5dc0: 36 34 36 32 33 36 64 33 66 62 63 61 36 32 39 38 646236d3fbca6298
5dd0: 31 33 62 32 30 64 30 37 35 66 30 30 66 33 65 64 13b20d075f00f3ed
5de0: 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 6"../*.** 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 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
a2f0: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 ETE_NOENT (
a300: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a310: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 23<<8)).#define
a320: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
a330: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
a340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
a350: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
a360: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
a370: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
a380: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
a390: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
a3a0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
a3b0: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
a3c0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
a3d0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
a3e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
a3f0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
a400: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
a410: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
a420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
a430: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 TOPEN_FULLPATH
a440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
a450: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a TOPEN | (3<<8)).
a460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
a470: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 ORRUPT_VTAB
a480: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
a490: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 ORRUPT | (1<<8))
a4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a4b0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
a4c0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
a4d0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
a4e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a4f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
a500: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
a510: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
a520: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
a530: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 ITE_ABORT_ROLLBA
a540: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c CK (SQL
a550: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c ITE_ABORT | (2<<
a560: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8))../*.** CAPI3
a570: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
a580: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
a590: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
a5a0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
a5b0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
a5c0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
a5d0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
a5e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
a5f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
a600: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
a610: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
a620: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
a630: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 en] method..*/.#
a640: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a650: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
a660: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 0x00000001
a670: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a680: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a6a0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
a6b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 0x00000002
a6c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a6d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a6f0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
a700: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 0x00000004
a710: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a720: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a740: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
a750: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 0x00000008
a760: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a780: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
a790: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 0x00000010
a7a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a7c0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 EN_AUTOPROXY
a7d0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 0x00000020
a7e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a7f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a800: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 EN_URI
a810: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 0x00000040
a820: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a830: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a850: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 EN_MEMORY
a860: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 0x00000080
a870: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a880: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a8a0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
a8b0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 0x00000100
a8c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a8e0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
a8f0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 0x00000200
a900: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a920: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
a930: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 0x00000400
a940: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a960: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
a970: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 0x00000800
a980: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a9a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
a9b0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 0x00001000
a9c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a9e0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
a9f0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 0x00002000
aa00: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
aa10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aa20: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
aa30: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 L 0x00004000
aa40: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
aa50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aa60: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 EN_NOMUTEX
aa70: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 0x00008000
aa80: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
aa90: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
aaa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aab0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 EN_FULLMUTEX
aac0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 0x00010000
aad0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
aae0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
aaf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
ab00: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 EN_SHAREDCACHE
ab10: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 0x00020000
ab20: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
ab30: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
ab40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
ab50: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
ab60: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 0x00040000
ab70: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
ab80: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
ab90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aba0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 EN_WAL
abb0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 0x00080000
abc0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a /* VFS only */..
abd0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 /* Reserved:
abe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
abf0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 0x00F00000
ac00: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
ac10: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 EF: Device Chara
ac20: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a cteristics.**.**
ac30: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
ac40: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
ac50: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 od of the [sqlit
ac60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
ac70: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 * object returns
ac80: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
ac90: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 h is a vector of
aca0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
acb0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
acc0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
acd0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
ace0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
acf0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
ad00: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
ad10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
ad20: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
ad30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
ad40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
ad50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
ad60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
ad70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
ad80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
ad90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
ada0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
adb0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
adc0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
add0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
ade0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
adf0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
ae00: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
ae10: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
ae20: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
ae30: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
ae40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
ae50: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
ae60: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
ae70: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
ae80: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
ae90: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
aea0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
aeb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
aec0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
aed0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
aee0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
aef0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
af00: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
af10: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
af20: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
af30: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
af40: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
af50: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
af60: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 * to xWrite().
af70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
af80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
af90: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 RITE property me
afa0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 ans that.** afte
afb0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 r reboot followi
afc0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f ng a crash or po
afd0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e wer loss, the on
afe0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a ly bytes in a.**
aff0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 file that were
b000: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 written at the a
b010: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c pplication level
b020: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e might have chan
b030: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ged.** and that
b040: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 adjacent bytes,
b050: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 even bytes withi
b060: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f n the same secto
b070: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 r are.** guarant
b080: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e eed to be unchan
b090: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ged..*/.#define
b0a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
b0b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
b0c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
b0d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
b0e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
b0f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
b100: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
b110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
b120: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
b130: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
b140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
b150: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
b160: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
b170: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
b180: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
b190: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
b1a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
b1b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
b1c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
b1d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
b1e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
b1f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
b200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
b210: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
b220: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
b230: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
b240: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
b250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
b260: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
b270: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
b280: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
b290: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
b2a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
b2b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
b2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
b2d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
b2e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
b2f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
b300: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
b310: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
b320: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
b330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
b340: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
b350: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
b360: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
b370: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
b380: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 Levels.**.** SQ
b390: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 Lite uses one of
b3a0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
b3b0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
b3c0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
b3d0: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
b3e0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
b3f0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
b400: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
b410: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
b420: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
b430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
b440: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
b450: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
b460: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
b470: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
b480: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
b490: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
b4a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
b4b0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
b4c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
b4d0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
b4e0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
b4f0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
b500: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a tion Type Flags.
b510: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
b520: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
b530: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
b540: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
b550: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
b560: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
b570: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 ination of.** th
b580: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ese integer valu
b590: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 es as the second
b5a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
b5b0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 When the SQLITE
b5c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 _SYNC_DATAONLY f
b5d0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 lag is used, it
b5e0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a means that the.*
b5f0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e * sync operation
b600: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 only needs to f
b610: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 lush data to mas
b620: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 s storage. Inod
b630: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
b640: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 need not be flu
b650: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 shed. If the low
b660: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 er four bits of
b670: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 the flag.** equa
b680: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f l SQLITE_SYNC_NO
b690: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 RMAL, that means
b6a0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 to use normal f
b6b0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 sync() semantics
b6c0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 ..** If the lowe
b6d0: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 r four bits equa
b6e0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 l SQLITE_SYNC_FU
b6f0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a LL, that means.*
b700: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 * to use Mac OS
b710: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
b720: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
b730: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f c()..**.** Do no
b740: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 t confuse the SQ
b750: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
b760: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
b770: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 _FULL flags.** w
b780: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 ith the [PRAGMA
b790: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 synchronous]=NOR
b7a0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 MAL and [PRAGMA
b7b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c synchronous]=FUL
b7c0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 L.** settings.
b7d0: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 The [synchronous
b7e0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 pragma] determi
b7f0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 nes when calls t
b800: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 o the.** xSync V
b810: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 FS method occur
b820: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 and applies unif
b830: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c ormly across all
b840: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 platforms..** T
b850: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
b860: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
b870: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
b880: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a determine how.*
b890: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 * energetic or r
b8a0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 igorous or force
b8b0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 ful the sync ope
b8c0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a rations are and.
b8d0: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 ** only make a d
b8e0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 ifference on Mac
b8f0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 OSX for the def
b900: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 ault SQLite code
b910: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 ..** (Third-part
b920: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 y VFS implementa
b930: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f tions might also
b940: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
b950: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e ction.** between
b960: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
b970: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
b980: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d YNC_FULL, but am
b990: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 ong the.** opera
b9a0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 ting systems nat
b9b0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 ively supported
b9c0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 by SQLite, only
b9d0: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 Mac OSX.** cares
b9e0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 about the diffe
b9f0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 rence.).*/.#defi
ba00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e ne SQLITE_SYNC_N
ba10: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 ORMAL 0x0
ba20: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
ba30: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 ITE_SYNC_FULL
ba40: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 0x00003.#
ba50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
ba60: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 NC_DATAONLY
ba70: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 0x00010../*.**
ba80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
ba90: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 erface Open File
baa0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e Handle.**.** An
bab0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
bac0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
bad0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 s an open file i
bae0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 n the .** [sqlit
baf0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 e3_vfs | OS inte
bb00: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 rface layer]. I
bb10: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
bb20: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d erface.** implem
bb30: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a entations will.*
bb40: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 * want to subcla
bb50: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 ss this object b
bb60: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 y appending addi
bb70: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a tional fields.**
bb80: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 for their own u
bb90: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 se. The pMethod
bba0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 s entry is a poi
bbb0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
bbc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
bbd0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
bbe0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 efines methods f
bbf0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a or performing.**
bc00: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
bc10: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 on the open file
bc20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
bc30: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
bc40: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 sqlite3_file;.s
bc50: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
bc60: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 le {. const str
bc70: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
bc80: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 ethods *pMethods
bc90: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f ; /* Methods fo
bca0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a r an open file *
bcb0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
bcc0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
bcd0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 ce File Virtual
bce0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a Methods Object.*
bcf0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 *.** Every file
bd00: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 opened by the [s
bd10: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
bd20: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 ] method populat
bd30: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 es an.** [sqlite
bd40: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 3_file] object (
bd50: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c or, more commonl
bd60: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 y, a subclass of
bd70: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
bd80: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 _file] object) w
bd90: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
bda0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
bdb0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 this object..**
bdc0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 This object defi
bdd0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 nes the methods
bde0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
bdf0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
be00: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 ns.** against th
be10: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 e open file repr
be20: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b esented by the [
be30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
be40: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ject..**.** If t
be50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
be60: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 xOpen] method se
be70: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
be80: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
be90: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
bea0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
beb0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
bec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
bed0: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
bee0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
bef0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 if the [sqlite3
bf00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f _vfs.xOpen] repo
bf10: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 rted that it fai
bf20: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c led. The.** onl
bf30: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 y way to prevent
bf40: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 a call to xClos
bf50: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 e following a fa
bf60: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 iled [sqlite3_vf
bf70: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 s.xOpen].** is f
bf80: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
bf90: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 vfs.xOpen] to se
bfa0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
bfb0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
bfc0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a ent.** to NULL..
bfd0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
bfe0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
bff0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
c000: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
c010: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
c020: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
c030: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
c040: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
c050: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
c060: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
c070: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
c080: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
c090: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
c0a0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
c0b0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
c0c0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
c0d0: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
c0e0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
c0f0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
c100: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
c110: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
c120: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
c130: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
c140: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
c150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
c160: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
c170: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
c180: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
c190: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c1a0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
c1b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c1c0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
c1d0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
c1e0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
c1f0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
c200: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
c210: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
c220: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
c230: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
c240: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
c250: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
c260: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
c270: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c280: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
c290: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
c2a0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
c2b0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
c2c0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
c2d0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
c2e0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
c2f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
c300: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
c310: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
c320: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
c330: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
c340: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
c350: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
c360: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
c370: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
c380: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
c390: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
c3a0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
c3b0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
c3c0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
c3d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
c3e0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
c3f0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
c400: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
c410: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
c420: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
c430: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
c440: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
c450: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
c460: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
c470: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
c480: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
c490: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
c4a0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
c4b0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
c4c0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
c4d0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
c4e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
c4f0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
c500: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
c510: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
c520: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
c530: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
c540: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
c550: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
c560: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
c570: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
c580: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
c590: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
c5a0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
c5b0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
c5c0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
c5d0: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
c5e0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 wn use..** A [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
c600: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f TATE | list of o
c610: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
c620: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
c630: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
c640: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
c650: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
c660: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
c670: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
c680: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
c690: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
c6a0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
c6b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
c6c0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
c6d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
c6e0: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
c6f0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
c700: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
c710: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
c720: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
c730: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
c740: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
c750: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
c760: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
c770: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
c780: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
c790: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
c7a0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
c7b0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
c7c0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
c7d0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
c7e0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
c7f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
c800: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
c810: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
c820: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
c830: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
c840: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
c850: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
c860: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c870: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
c880: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
c890: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
c8a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c8b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
c8c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c8d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
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 34 4b 5d 0a IOCAP_ATOMIC4K].
c900: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c910: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
c920: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c930: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
c940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c950: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
c960: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
c970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
c980: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
c990: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
c9a0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
c9b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
c9c0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
c9d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
c9e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
c9f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
ca00: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
ca10: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
ca20: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
ca30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
ca40: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
ca50: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
ca60: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
ca70: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
ca80: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
ca90: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
caa0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
cab0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
cac0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
cad0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
cae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
caf0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
cb00: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
cb10: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
cb20: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
cb30: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
cb40: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
cb50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
cb60: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
cb70: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
cb80: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
cb90: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
cba0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
cbb0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
cbc0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
cbd0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
cbe0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
cbf0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
cc00: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
cc10: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
cc20: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
cc30: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
cc40: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
cc50: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
cc60: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
cc70: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
cc80: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
cc90: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
cca0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
ccb0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
ccc0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
ccd0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
cce0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
ccf0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
cd00: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
cd10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
cd20: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
cd30: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
cd40: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
cd50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
cd60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
cd70: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
cd80: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
cd90: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
cda0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
cdb0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
cdc0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
cdd0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
cde0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
cdf0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
ce00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
ce10: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
ce20: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
ce30: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
ce40: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
ce50: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
ce60: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
ce70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
ce80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
ce90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
cea0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
ceb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
cec0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
ced0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
cee0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
cef0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
cf00: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
cf10: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
cf20: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
cf30: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
cf40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
cf50: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
cf60: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
cf70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
cf80: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
cf90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
cfa0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
cfb0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
cfc0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
cfd0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
cfe0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
cff0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
d000: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
d010: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
d020: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
d030: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
d040: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
d050: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
d060: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
d070: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
d080: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
d090: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
d0a0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
d0b0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
d0c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
d0d0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
d0e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
d0f0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
d100: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
d110: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
d120: 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 n 2 */. /* Addi
d130: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d tional methods m
d140: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
d150: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a uture releases *
d160: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
d170: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 3REF: Standard F
d180: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f ile Control Opco
d190: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 des.**.** These
d1a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
d1b0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
d1c0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
d1d0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
d1e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
d1f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
d200: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
d210: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
d220: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
d230: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 e..**.** The [SQ
d240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
d250: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
d260: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
d270: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
d280: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
d290: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
d2a0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
d2b0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
d2c0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
d2d0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
d2e0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
d2f0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
d300: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
d310: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
d320: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
d330: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
d340: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
d350: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
d360: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
d370: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
d380: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
d390: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
d3a0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
d3b0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
d3c0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
d3d0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 SQLITE_TEST.** i
d3e0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 s defined..** <u
d3f0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 l>.** <li>[[SQLI
d400: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
d410: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NT]].** The [SQL
d420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
d430: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 INT] opcode is u
d440: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f sed by SQLite to
d450: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a give the VFS.**
d460: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 layer a hint of
d470: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 how large the d
d480: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
d490: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 l grow to be dur
d4a0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 ing the.** curre
d4b0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 nt transaction.
d4c0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
d4d0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 t guaranteed to
d4e0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 be accurate but
d4f0: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 it.** is often c
d500: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 lose. The under
d510: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 lying VFS might
d520: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c choose to preall
d530: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a ocate database.*
d540: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 * file space bas
d550: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 ed on this hint
d560: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 in order to help
d570: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 writes to the d
d580: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
d590: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a run faster..**.*
d5a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
d5b0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
d5c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
d5d0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
d5e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
d5f0: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 d to request tha
d600: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 t the VFS.** ext
d610: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 ends and truncat
d620: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
d630: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f file in chunks o
d640: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 f a size specifi
d650: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 ed.** by the use
d660: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 r. The fourth ar
d670: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
d680: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
d690: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f )] should .** po
d6a0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 int to an intege
d6b0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e r (type int) con
d6c0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 taining the new
d6d0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 chunk-size to us
d6e0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d e.** for the nom
d6f0: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e inated database.
d700: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 Allocating data
d710: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 base file space
d720: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e in large.** chun
d730: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 ks (say 1MB at a
d740: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 time), may redu
d750: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 ce file-system f
d760: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 ragmentation and
d770: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 .** improve perf
d780: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 ormance on some
d790: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c systems..**.** <
d7a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d7b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d L_FILE_POINTER]]
d7c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
d7d0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
d7e0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ER] opcode is us
d7f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 ed to obtain a p
d800: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
d810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
d820: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 object associate
d830: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 d with a particu
d840: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
d850: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
d860: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d870: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f le_control()] do
d880: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a cumentation for.
d890: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
d8a0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
d8b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d8c0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
d8d0: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c ]].** ^(The [SQL
d8e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
d8f0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 MITTED] opcode i
d900: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 s generated inte
d910: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c rnally by.** SQL
d920: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 ite and sent to
d930: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 all VFSes in pla
d940: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 ce of a call to
d950: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
d960: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 .** when the dat
d970: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d980: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e has [PRAGMA syn
d990: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f chronous] set to
d9a0: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 OFF.)^.** Some
d9b0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
d9c0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e s need this sign
d9d0: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f al in order to o
d9e0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 perate correctly
d9f0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 .** when [PRAGMA
da00: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 synchronous | P
da10: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
da20: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 s=OFF] is set, b
da30: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 ut most .** VFSe
da40: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 s do not need th
da50: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 is signal and sh
da60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
da70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
da80: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
da90: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
daa0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f l [sqlite3_file_
dab0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 control()] with
dac0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 this.** opcode a
dad0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
dae0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
daf0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
db00: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a ialized VFSes.**
db10: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
db20: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
db30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
db40: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
db50: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
db60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
db70: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
db80: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
db90: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
dba0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
dbb0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
dbc0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
dbd0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
dbe0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
dbf0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
dc00: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
dc10: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
dc20: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
dc30: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
dc40: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
dc50: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
dc60: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
dc70: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
dc80: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
dc90: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
dca0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
dcb0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
dcc0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
dcd0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
dce0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
dcf0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
dd00: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
dd10: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
dd20: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
dd30: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
dd40: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
dd50: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
dd60: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
dd70: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
dd80: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
dd90: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
dda0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
ddb0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
ddc0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
ddd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
dde0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
ddf0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
de00: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
de10: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
de20: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
de30: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
de40: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
de50: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
de60: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
de70: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
de80: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
de90: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
dea0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
deb0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
dec0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
ded0: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
dee0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
def0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
df00: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
df10: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
df20: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
df30: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
df40: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
df50: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
df60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
df70: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
df80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
df90: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d TL_PERSIST_WAL]]
dfa0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
dfb0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
dfc0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 AL] opcode is us
dfd0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
dfe0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
dff0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 tent [WAL | Writ
e000: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 e Ahead Log] set
e010: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c ting. By defaul
e020: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 t, the auxiliary
e030: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 .** write ahead
e040: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d log and shared m
e050: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 emory files used
e060: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e for transaction
e070: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 control.** are
e080: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
e090: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c leted when the l
e0a0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e atest connection
e0b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
e0c0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 .** closes. Set
e0d0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 ting persistent
e0e0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 WAL mode causes
e0f0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 those files to p
e100: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 ersist after.**
e110: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 close. Persisti
e120: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 ng the files is
e130: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 useful when othe
e140: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 r processes that
e150: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 do not.** have
e160: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e write permission
e170: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 on the director
e180: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 y containing the
e190: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
e1a0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 ant.** to read t
e1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
e1c0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 , as the WAL and
e1d0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
e1e0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a iles must exist.
e1f0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 ** in order for
e200: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 the database to
e210: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 be readable. Th
e220: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
e230: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
e240: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
e250: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
e260: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
e270: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
e280: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
e290: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
e2a0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 able persistent
e2b0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f WAL mode or 1 to
e2c0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 enable persiste
e2d0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 nt.** WAL mode.
e2e0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
e2f0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
e300: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
e310: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
e320: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 * WAL persistenc
e330: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
e340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e350: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
e360: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
e370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
e380: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
e390: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
e3a0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
e3b0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
e3c0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
e3d0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
e3e0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
e3f0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
e400: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
e410: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
e420: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
e430: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
e440: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
e450: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
e460: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
e470: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
e480: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
e490: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
e4a0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
e4b0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
e4c0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
e4d0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
e4e0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
e4f0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
e500: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
e510: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
e520: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
e530: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
e540: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
e550: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
e560: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
e570: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
e580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
e590: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d CNTL_OVERWRITE]]
e5a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
e5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
e5c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f ] opcode is invo
e5d0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 ked by SQLite af
e5e0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 ter opening.** a
e5f0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 write transacti
e600: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 on to indicate t
e610: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 hat, unless it i
e620: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f s rolled back fo
e630: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e r some.** reason
e640: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 , the entire dat
e650: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
e660: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 be overwritten b
e670: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a y the current .*
e680: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 * transaction. T
e690: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 his is used by V
e6a0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 ACUUM operations
e6b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
e6c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
e6d0: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ME]].** ^The [SQ
e6e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
e6f0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 ME] opcode can b
e700: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
e710: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a the names of.**
e720: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 all [VFSes] in
e730: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 the VFS stack.
e740: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 The names are of
e750: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 all VFS shims a
e760: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 nd the.** final
e770: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 bottom-level VFS
e780: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 are written int
e790: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
e7a0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
e7b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
e7c0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 d the result is
e7d0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 stored in the ch
e7e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 ar* variable.**
e7f0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 that the fourth
e800: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 parameter of [sq
e810: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
e820: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e ol()] points to.
e830: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 .** The caller i
e840: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
e850: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 r freeing the me
e860: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 mory when done.
e870: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 As with.** all
e880: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 file-control act
e890: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e ions, there is n
e8a0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 o guarantee that
e8b0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 this will actua
e8c0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 lly.** do anythi
e8d0: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f ng. Callers sho
e8e0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 uld initialize t
e8f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
e900: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e to a NULL.** p
e910: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 ointer in case t
e920: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
e930: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e is not implemen
e940: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d ted. This file-
e950: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e control.** is in
e960: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e tended for diagn
e970: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a ostic use only..
e980: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
e990: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
e9a0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
e9b0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
e9c0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
e9d0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
e9e0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
e9f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
ea00: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
ea10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
ea20: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
ea30: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
ea40: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
ea50: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
ea60: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
ea70: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
ea80: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
ea90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
eaa0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
eab0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
eac0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
ead0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
eae0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
eaf0: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
eb00: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
eb10: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
eb20: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
eb30: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
eb40: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
eb50: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
eb60: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
eb70: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
eb80: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
eb90: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
eba0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
ebb0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
ebc0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
ebd0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
ebe0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
ebf0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
ec00: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
ec10: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
ec20: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
ec30: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
ec40: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
ec50: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
ec60: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
ec70: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
ec80: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
ec90: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
eca0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
ecb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ecc0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
ecd0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
ece0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
ecf0: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
ed00: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
ed10: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
ed20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
ed30: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
ed40: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ed50: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
ed60: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
ed70: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
ed80: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
ed90: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
eda0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
edb0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
edc0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
edd0: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 d statement. ^I
ede0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
edf0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
ee00: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
ee10: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 .** any result c
ee20: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ode other than [
ee30: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 SQLITE_OK] or [S
ee40: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
ee50: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
ee60: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f hat the VFS enco
ee70: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 untered an error
ee80: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 while handling
ee90: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 the [PRAGMA] and
eea0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 the.** compilat
eeb0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d ion of the PRAGM
eec0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 A fails with an
eed0: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 error. ^The [SQ
eee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
eef0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
ef00: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 ol occurs at the
ef10: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 beginning of pr
ef20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 agma statement a
ef30: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a nalysis and so.*
ef40: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 * it is able to
ef50: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 override built-i
ef60: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 n [PRAGMA] state
ef70: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ments..**.** <li
ef80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
ef90: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a BUSYHANDLER]].**
efa0: 20 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 ^This file-cont
efb0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b rol may be invok
efc0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 ed by SQLite on
efd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
efe0: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 e handle.** shor
eff0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 tly after it is
f000: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 opened in order
f010: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 to provide a cus
f020: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 tom VFS with acc
f030: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f ess.** to the co
f040: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 nnections busy-h
f050: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e andler callback.
f060: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
f070: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a of type (void *
f080: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 *).** - an array
f090: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 of two (void *)
f0a0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 values. The fir
f0b0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 st (void *) actu
f0c0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 ally points.** t
f0d0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 o a function of
f0e0: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f type (int (*)(vo
f0f0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 id *)). In order
f100: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 to invoke the c
f110: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 onnections.** bu
f120: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 sy-handler, this
f130: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
f140: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
f150: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 the second (voi
f160: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 d *) in.** the a
f170: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 rray as the only
f180: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 argument. If it
f190: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
f1a0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 o, then the oper
f1b0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
f1c0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 be retried. If i
f1d0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 t returns zero,
f1e0: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 the custom VFS s
f1f0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 hould abandon th
f200: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 e.** current ope
f210: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ration..**.** <l
f220: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
f230: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a _TEMPFILENAME]].
f240: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 ** ^Application
f250: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 can invoke this
f260: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20 file-control to
f270: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 have SQLite gene
f280: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 rate a.** tempor
f290: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 ary filename usi
f2a0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
f2b0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f rithm that is fo
f2c0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 llowed to genera
f2d0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
f2e0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 filenames for TE
f2f0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 MP tables and ot
f300: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 her internal use
f310: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d s. The.** argum
f320: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ent should be a
f330: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c char** which wil
f340: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 l be filled with
f350: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a the filename.**
f360: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
f370: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
f380: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
f390: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c oc()]. The call
f3a0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 er should.** inv
f3b0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
f3c0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 e()] on the resu
f3d0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 lt to avoid a me
f3e0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a mory leak..**.**
f3f0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
f400: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
f410: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
f420: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
f430: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b SQLITE_GET_LOCK
f440: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 PROXYFILE
f450: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
f460: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 SQLITE_SET_LOCKP
f470: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 ROXYFILE
f480: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
f490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f QLITE_LAST_ERRNO
f4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
f4b0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
f4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
f4d0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
f4e0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
f4f0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
f500: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
f510: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
f520: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
f530: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
f540: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
f550: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
f560: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
f570: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
f580: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
f590: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
f5a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f5b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
f5c0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
f5d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
f5e0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
f5f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
f600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
f610: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
f620: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
f630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
f640: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
f650: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
f660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
f670: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
f680: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
f690: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
f6a0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
f6b0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
f6c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
f6d0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
f6e0: 20 20 20 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 16../*.**
f6f0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
f700: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 Handle.**.** Th
f710: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
f720: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
f730: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
f740: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
f750: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
f760: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
f770: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
f780: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
f790: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
f7a0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
f7b0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
f7c0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
f7d0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
f7e0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
f7f0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
f800: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
f810: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
f820: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
f830: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
f840: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
f850: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
f860: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
f870: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
f880: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
f890: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ject.**.** An in
f8a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 stance of the sq
f8b0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
f8c0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
f8d0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a erface between.*
f8e0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * the SQLite cor
f8f0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c e and the underl
f900: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
f910: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 ystem. The "vfs
f920: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 ".** in the name
f930: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 of the object s
f940: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 tands for "virtu
f950: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e al file system".
f960: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 See.** the [VF
f970: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 S | VFS document
f980: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 ation] for furth
f990: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a er information..
f9a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 **.** The value
f9b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 of the iVersion
f9c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
f9d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
f9e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 larger in.** fut
f9f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
fa00: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f SQLite. Additio
fa10: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 nal fields may b
fa20: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 e appended to th
fa30: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 is.** object whe
fa40: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 n the iVersion v
fa50: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 alue is increase
fa60: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 d. Note that th
fa70: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f e structure.** o
fa80: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
fa90: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 s object changes
faa0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 in the transact
fab0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 ion between.** S
fac0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
fad0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 5.9 and 3.6.0 an
fae0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 d yet the iVersi
faf0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 on field was not
fb00: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a .** modified..**
fb10: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
fb20: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
fb30: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
fb40: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
fb50: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
fb60: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
fb70: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
fb80: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
fb90: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
fba0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
fbb0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
fbc0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
fbd0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
fbe0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
fbf0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
fc00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
fc10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
fc20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
fc30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
fc40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
fc50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
fc60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
fc70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
fc80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
fc90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
fca0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
fcb0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
fcc0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
fcd0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
fce0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
fcf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
fd00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
fd10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
fd20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
fd30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
fd40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
fd50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
fd60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
fd70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
fd80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
fd90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
fda0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
fdb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
fdc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
fdd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
fde0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
fdf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
fe00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
fe10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
fe20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
fe30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
fe40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
fe50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
fe60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
fe70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
fe80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
fe90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
fea0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
feb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
fec0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
fed0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c .xOpen]].** ^SQL
fee0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 ite guarantees t
fef0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
ff00: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
ff10: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
ff20: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
ff30: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
ff40: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
ff50: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 lPathname() with
ff60: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 an optional suf
ff70: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 fix added..** ^I
ff80: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 f a suffix is ad
ff90: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 ded to the zFile
ffa0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 name parameter,
ffb0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 it will.** consi
ffc0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 st of a single "
ffd0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c -" character fol
ffe0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 lowed by no more
fff0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 than.** 11 alph
10000 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 anumeric and/or
10010 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a "-" characters..
10020 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 ** ^SQLite furth
10030 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 er guarantees th
10040 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 at.** the string
10050 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
10060 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 nd unchanged unt
10070 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a il xClose() is.*
10080 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 * called. Becaus
10090 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 e of the previou
100a0 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 s sentence,.** t
100b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
100c0 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f ] can safely sto
100d0 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 re a pointer to
100e0 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 the.** filename
100f0 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 if it needs to r
10100 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 emember the file
10110 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 name for some re
10120 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ason..** If the
10130 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
10140 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 ter to xOpen is
10150 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
10160 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 hen xOpen.** mus
10170 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e t invent its own
10180 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 temporary name
10190 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e for the file. ^
101a0 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a Whenever the .**
101b0 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d xFilename param
101c0 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 eter is NULL it
101d0 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 will also be the
101e0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a case that the.*
101f0 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 * flags paramete
10200 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b r will include [
10210 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
10220 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a TEONCLOSE]..**.*
10230 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
10240 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 ment to xOpen()
10250 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 includes all bit
10260 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 s set in.** the
10270 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
10280 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
10290 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 v2()]. Or if [s
102a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
102b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 * or [sqlite3_op
102c0 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c en16()] is used,
102d0 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c then flags incl
102e0 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a udes at least.**
102f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
10300 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
10310 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e TE_OPEN_CREATE].
10320 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 .** If xOpen()
10330 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
10340 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
10350 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
10360 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 o.** include [SQ
10370 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
10380 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 LY]. Other bits
10390 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d in *pOutFlags m
103a0 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ay be set..**.**
103b0 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ^(SQLite will a
103c0 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
103d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
103e0 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
103f0 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
10400 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
10410 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
10420 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
10430 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
10440 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
10450 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
10460 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
10470 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
10480 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
10490 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
104a0 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
104b0 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
104c0 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
104d0 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
104e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
104f0 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
10500 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
10510 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
10520 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
10530 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c PEN_WAL].** </ul
10540 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 >)^.**.** The fi
10550 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
10560 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
10570 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
10580 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
10590 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c the way it deal
105a0 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 s with files. F
105b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 or example, an a
105c0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 pplication.** th
105d0 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 at does not care
105e0 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 about crash rec
105f0 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 overy or rollbac
10600 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 k might make.**
10610 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f the open of a jo
10620 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d urnal file a no-
10630 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 op. Writes to t
10640 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c his journal woul
10650 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d d.** also be no-
10660 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 ops, and any att
10670 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 empt to read the
10680 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 journal would r
10690 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f eturn.** SQLITE_
106a0 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 IOERR. Or the i
106b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
106c0 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 ght recognize th
106d0 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a at a database.**
106e0 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f file will be do
106f0 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 ing page-aligned
10700 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e sector reads an
10710 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 d writes in a ra
10720 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e ndom.** order an
10730 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f d set up its I/O
10740 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 subsystem accor
10750 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 dingly..**.** SQ
10760 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 Lite might also
10770 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
10780 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
10790 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 o the xOpen meth
107a0 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a od:.**.** <ul>.*
107b0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
107c0 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
107d0 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 E].** <li> [SQLI
107e0 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
107f0 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a E].** </ul>.**.*
10800 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 * The [SQLITE_OP
10810 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
10820 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
10830 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
10840 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
10850 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e it is closed. ^
10860 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
10870 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
10880 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 ** will be set f
10890 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 or TEMP database
108a0 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 s and their jour
108b0 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a nals, transient.
108c0 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e ** databases, an
108d0 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a d subjournals..*
108e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
108f0 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
10900 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 ] flag is always
10910 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 used in conjunc
10920 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
10930 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
10940 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 EATE] flag, whic
10950 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 h are both direc
10960 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 tly.** analogous
10970 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 to the O_EXCL a
10980 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 nd O_CREAT flags
10990 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 of the POSIX op
109a0 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 en().** API. Th
109b0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 e SQLITE_OPEN_EX
109c0 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 CLUSIVE flag, wh
109d0 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 en paired with t
109e0 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 he .** SQLITE_OP
109f0 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 EN_CREATE, is us
10a00 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
10a10 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 hat file should
10a20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 always.** be cre
10a30 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 ated, and that i
10a40 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 t is an error if
10a50 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 it already exis
10a60 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e ts..** It is <i>
10a70 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 not</i> used to
10a80 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c indicate the fil
10a90 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e e should be open
10aa0 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 ed .** for exclu
10ab0 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a sive access..**.
10ac0 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f ** ^At least szO
10ad0 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d sFile bytes of m
10ae0 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 emory are alloca
10af0 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a ted by SQLite.**
10b00 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 to hold the [s
10b10 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 qlite3_file] str
10b20 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 ucture passed as
10b30 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
10b40 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e gument to xOpen.
10b50 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 The xOpen meth
10b60 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 od does not have
10b70 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 to.** allocate
10b80 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 the structure; i
10b90 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 t should just fi
10ba0 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 ll it in. Note
10bb0 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 that.** the xOpe
10bc0 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 n method must se
10bd0 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
10be0 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 le.pMethods to e
10bf0 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 ither.** a valid
10c00 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
10c10 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 hods] object or
10c20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 to NULL. xOpen
10c30 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 must do.** this
10c40 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e even if the open
10c50 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 fails. SQLite
10c60 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 expects that the
10c70 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
10c80 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e ethods.** elemen
10c90 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 t will be valid
10ca0 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 after xOpen retu
10cb0 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f rns regardless o
10cc0 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a f the success.**
10cd0 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 or failure of t
10ce0 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a he xOpen call..*
10cf0 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
10d00 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 fs.xAccess]].**
10d10 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d ^The flags argum
10d20 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 ent to xAccess()
10d30 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f may be [SQLITE_
10d40 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a ACCESS_EXISTS].*
10d50 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 * to test for th
10d60 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 e existence of a
10d70 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 file, or [SQLIT
10d80 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
10d90 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 TE] to.** test w
10da0 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
10db0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
10dc0 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 itable, or [SQLI
10dd0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a TE_ACCESS_READ].
10de0 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 ** to test wheth
10df0 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 er a file is at
10e00 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 least readable.
10e10 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 The file can b
10e20 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 e a.** directory
10e30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
10e40 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
10e50 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
10e60 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
10e70 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
10e80 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
10e90 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
10ea0 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
10eb0 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
10ec0 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
10ed0 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
10ee0 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
10ef0 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
10f00 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
10f10 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
10f20 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
10f30 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
10f40 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
10f50 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
10f60 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
10f70 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
10f80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
10f90 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
10fa0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
10fb0 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
10fc0 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
10fd0 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
10fe0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
10ff0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
11000 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 leep(), xCurrent
11010 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 Time(), and xCur
11020 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a rentTimeInt64().
11030 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ** interfaces ar
11040 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 e not strictly a
11050 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c part of the fil
11060 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 esystem, but the
11070 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 y are.** include
11080 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 d in the VFS str
11090 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c ucture for compl
110a0 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 eteness..** The
110b0 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 xRandomness() fu
110c0 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 nction attempts
110d0 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 to return nBytes
110e0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f bytes.** of goo
110f0 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d d-quality random
11100 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 ness into zOut.
11110 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
11120 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 e is.** the actu
11130 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 al number of byt
11140 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
11150 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 obtained..** Th
11160 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
11170 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c d causes the cal
11180 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 ling thread to s
11190 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c leep for at.** l
111a0 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 east the number
111b0 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 of microseconds
111c0 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 given. ^The xCu
111d0 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
111e0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
111f0 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
11200 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
11210 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 t date and time
11220 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 as.** a floating
11230 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a point value..**
11240 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
11250 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
11260 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 returns, as an
11270 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c integer, the Jul
11280 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 ian.** Day Numbe
11290 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 r multiplied by
112a0 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 86400000 (the nu
112b0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
112c0 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 onds in .** a 24
112d0 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a -hour day). .**
112e0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
112f0 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 e the xCurrentTi
11300 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
11310 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 to get the curr
11320 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 ent.** date and
11330 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 time if that met
11340 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 hod is available
11350 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 (if iVersion is
11360 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 2 or .** greate
11370 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 r and the functi
11380 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
11390 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c t NULL) and will
113a0 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f fall back.** to
113b0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 xCurrentTime()
113c0 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 if xCurrentTimeI
113d0 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 nt64() is unavai
113e0 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lable..**.** ^Th
113f0 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c e xSetSystemCall
11400 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 (), xGetSystemCa
11410 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 ll(), and xNestS
11420 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 ystemCall() inte
11430 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
11440 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 t used by the SQ
11450 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 Lite core. Thes
11460 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 e optional inter
11470 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
11480 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 ed.** by some VF
11490 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 Ses to facilitat
114a0 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 e testing of the
114b0 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 VFS code. By ov
114c0 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 erriding .** sys
114d0 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 tem calls with f
114e0 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 unctions under i
114f0 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 ts control, a te
11500 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a st program can.*
11510 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 * simulate fault
11520 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 s and error cond
11530 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c itions that woul
11540 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 d otherwise be d
11550 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 ifficult.** or i
11560 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 mpossible to ind
11570 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 uce. The set of
11580 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 system calls th
11590 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 at can be overri
115a0 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 dden.** varies f
115b0 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 rom one VFS to a
115c0 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d nother, and from
115d0 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 one version of
115e0 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 the same VFS to
115f0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 the.** next. Ap
11600 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
11610 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 use these interf
11620 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 aces must be pre
11630 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a pared for any.**
11640 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 or all of these
11650 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 interfaces to b
11660 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 e NULL or for th
11670 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 eir behavior to
11680 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f change.** from o
11690 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 ne release to th
116a0 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 e next. Applica
116b0 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 tions must not a
116c0 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 ttempt to access
116d0 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 .** any of these
116e0 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 methods if the
116f0 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 iVersion of the
11700 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e VFS is less than
11710 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 3..*/.typedef s
11720 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
11730 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 s sqlite3_vfs;.t
11740 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
11750 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
11760 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 r)(void);.struct
11770 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 sqlite3_vfs {.
11780 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 int iVersion;
11790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
117a0 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e ucture version n
117b0 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 umber (currently
117c0 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 3) */. int szO
117d0 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 sFile;
117e0 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 /* Size of sub
117f0 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f classed sqlite3_
11800 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 file */. int mx
11810 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 Pathname;
11820 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 /* Maximum fi
11830 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 le pathname leng
11840 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f th */. sqlite3_
11850 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 vfs *pNext;
11860 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 /* Next registe
11870 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e red VFS */. con
11880 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 st char *zName;
11890 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
118a0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 this virtual fi
118b0 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 le system */. v
118c0 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
118d0 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 /* Point
118e0 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f er to applicatio
118f0 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 n-specific data
11900 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e */. int (*xOpen
11910 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
11920 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
11930 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e, sqlite3_file*
11940 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
11950 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
11960 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 *pOutFlags);. i
11970 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 nt (*xDelete)(sq
11980 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
11990 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
119a0 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 nt syncDir);. i
119b0 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 nt (*xAccess)(sq
119c0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
119d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
119e0 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
119f0 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
11a00 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 *xFullPathname)(
11a10 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
11a20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
11a30 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 int nOut, char
11a40 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a *zOut);. void *
11a50 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 (*xDlOpen)(sqlit
11a60 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
11a70 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b har *zFilename);
11a80 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 . void (*xDlErr
11a90 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a or)(sqlite3_vfs*
11aa0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
11ab0 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 r *zErrMsg);. v
11ac0 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 oid (*(*xDlSym)(
11ad0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 sqlite3_vfs*,voi
11ae0 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a d*, const char *
11af0 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b zSymbol))(void);
11b00 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f . void (*xDlClo
11b10 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a se)(sqlite3_vfs*
11b20 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 , void*);. int
11b30 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 (*xRandomness)(s
11b40 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
11b50 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f nByte, char *zO
11b60 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c ut);. int (*xSl
11b70 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 eep)(sqlite3_vfs
11b80 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f *, int microseco
11b90 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 nds);. int (*xC
11ba0 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 urrentTime)(sqli
11bb0 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 te3_vfs*, double
11bc0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 *);. int (*xGet
11bd0 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 LastError)(sqlit
11be0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 e3_vfs*, int, ch
11bf0 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a ar *);. /*. **
11c00 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
11c10 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
11c20 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 n 1 of the sqlit
11c30 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a e_vfs object. *
11c40 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 * definition. T
11c50 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 hose that follow
11c60 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 are added in ve
11c70 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 rsion 2 or later
11c80 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 . */. int (*xC
11c90 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 urrentTimeInt64)
11ca0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 (sqlite3_vfs*, s
11cb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a qlite3_int64*);.
11cc0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
11cd0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
11ce0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e in versions 1 an
11cf0 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 d 2 of the sqlit
11d00 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
11d10 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 ** Those below a
11d20 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 re for version 3
11d30 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 and greater..
11d40 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 */. int (*xSetS
11d50 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
11d60 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
11d70 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
11d80 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
11d90 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 ;. sqlite3_sysc
11da0 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 all_ptr (*xGetSy
11db0 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
11dc0 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
11dd0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f ar *zName);. co
11de0 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 nst char *(*xNex
11df0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
11e00 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
11e10 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 char *zName);.
11e20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
11e30 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
11e40 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 n versions 1 thr
11e50 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 ough 3 of the sq
11e60 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e lite_vfs object.
11e70 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 . ** New fields
11e80 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
11e90 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 in figure versi
11ea0 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 ons. The iVersi
11eb0 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 on. ** value wi
11ec0 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 ll increment whe
11ed0 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 never this happe
11ee0 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a ns. . */.};../*
11ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
11f00 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 ags for the xAcc
11f10 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a ess VFS method.*
11f20 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
11f30 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e er constants can
11f40 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 be used as the
11f50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
11f60 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 to.** the xAcces
11f70 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b s method of an [
11f80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
11f90 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 ect. They deter
11fa0 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e mine.** what kin
11fb0 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 d of permissions
11fc0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
11fd0 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 hod is looking f
11fe0 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 or..** With SQLI
11ff0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
12000 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
12010 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 thod.** simply c
12020 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
12030 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a e file exists..*
12040 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
12050 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 CESS_READWRITE,
12060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
12070 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
12080 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 ther the named d
12090 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 irectory is both
120a0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
120b0 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 itable.** (in ot
120c0 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 her words, if fi
120d0 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 les can be added
120e0 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 , removed, and r
120f0 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a enamed within.**
12100 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e the directory).
12110 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 .** The SQLITE_A
12120 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
12130 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 constant is curr
12140 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 ently used only
12150 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f by the.** [temp_
12160 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
12170 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 pragma], though
12180 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 this could chang
12190 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
121a0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
121b0 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 te..** With SQLI
121c0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 TE_ACCESS_READ,
121d0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
121e0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
121f0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 ther the file is
12200 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
12210 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
12220 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a AD constant is.*
12230 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 * currently unus
12240 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 ed, though it mi
12250 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 ght be used in a
12260 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
12270 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f of.** SQLite..*/
12280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
12290 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
122a0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
122b0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
122c0 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 TE 1 /* Used b
122d0 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 y PRAGMA temp_st
122e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f ore_directory */
122f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
12300 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 ACCESS_READ
12310 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2 /* Unused *
12320 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
12330 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
12340 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 xShmLock VFS me
12350 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
12360 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
12370 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 ts define the va
12380 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 rious locking op
12390 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f erations.** allo
123a0 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c wed by the xShmL
123b0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 ock method of [s
123c0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
123d0 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c s]. The.** foll
123e0 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e owing are the on
123f0 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 ly legal combina
12400 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 tions of flags t
12410 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 o the.** xShmLoc
12420 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 k method:.**.**
12430 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 <ul>.** <li> SQ
12440 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 LITE_SHM_LOCK |
12450 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
12460 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
12470 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
12480 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
12490 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 E.** <li> SQLIT
124a0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
124b0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
124c0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
124d0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
124e0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
124f0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VE.** </ul>.**.*
12500 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 * When unlocking
12510 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 , the same SHARE
12520 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 D or EXCLUSIVE f
12530 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 lag must be supp
12540 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 lied as.** was g
12550 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 iven no the corr
12560 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 esponding lock.
12570 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d .**.** The xShm
12580 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 Lock method can
12590 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
125a0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
125b0 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 SHARED or.** bet
125c0 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
125d0 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 d EXCLUSIVE. It
125e0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 cannot transiti
125f0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 on between SHARE
12600 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 D.** and EXCLUSI
12610 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 VE..*/.#define S
12620 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
12630 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
12640 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
12650 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
12660 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 ne SQLITE_SHM_SH
12670 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 ARED 4.#de
12680 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
12690 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a EXCLUSIVE 8..
126a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
126b0 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b Maximum xShmLock
126c0 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 index.**.** The
126d0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
126e0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f on [sqlite3_io_
126f0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 methods] may use
12700 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
12710 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 en 0 and this up
12720 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 per bound as its
12730 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 "offset" argume
12740 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 nt..** The SQLit
12750 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 e core will neve
12760 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 r attempt to acq
12770 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 uire or release
12780 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 a.** lock outsid
12790 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a e of this range.
127a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
127b0 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 E_SHM_NLOCK
127c0 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8.../*.** CAP
127d0 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a I3REF: Initializ
127e0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 e The SQLite Lib
127f0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rary.**.** ^The
12800 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12810 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 ze() routine ini
12820 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 tializes the.**
12830 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
12840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 ^The sqlite3_sh
12850 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 utdown() routine
12860 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 .** deallocates
12870 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 any resources th
12880 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 at were allocate
12890 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 d by sqlite3_ini
128a0 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 tialize()..** Th
128b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
128c0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 designed to aid
128d0 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 in process init
128e0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a ialization and.*
128f0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d * shutdown on em
12900 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 bedded systems.
12910 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 Workstation app
12920 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a lications using.
12930 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c ** SQLite normal
12940 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ly do not need t
12950 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 o invoke either
12960 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
12970 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 s..**.** A call
12980 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
12990 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 alize() is an "e
129a0 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
129b0 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 f it is.** the f
129c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
129d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
129e0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 s invoked during
129f0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
12a00 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c .** the process,
12a10 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 or if it is the
12a20 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
12a30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
12a40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 is invoked.** f
12a50 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
12a60 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
12a70 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 own(). ^(Only a
12a80 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c n effective call
12a90 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 .** of sqlite3_i
12aa0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 nitialize() does
12ab0 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 any initializat
12ac0 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ion. All other
12ad0 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 calls.** are har
12ae0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
12af0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
12b00 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
12b10 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
12b20 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
12b30 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
12b40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
12b50 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 shutdown() since
12b60 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
12b70 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 3_initialize().
12b80 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 ^(Only.** an ef
12b90 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 fective call to
12ba0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
12bb0 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e () does any dein
12bc0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a itialization..**
12bd0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 All other valid
12be0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
12bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 3_shutdown() are
12c00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
12c10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 .)^.**.** The sq
12c20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12c30 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
12c40 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 threadsafe, but
12c50 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
12c60 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 ().** is not. T
12c70 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
12c80 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 own() interface
12c90 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c must only be cal
12ca0 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 led from a.** si
12cb0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c ngle thread. Al
12cc0 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 l open [database
12cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 connections] mu
12ce0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 st be closed and
12cf0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 all.** other SQ
12d00 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d Lite resources m
12d10 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 ust be deallocat
12d20 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f ed prior to invo
12d30 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f king.** sqlite3_
12d40 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a shutdown()..**.*
12d50 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 * Among other th
12d60 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 ings, ^sqlite3_i
12d70 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c nitialize() will
12d80 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
12d90 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 e3_os_init(). S
12da0 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 imilarly, ^sqlit
12db0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a e3_shutdown().**
12dc0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c will invoke sql
12dd0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a ite3_os_end()..*
12de0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
12df0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
12e00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
12e10 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
12e20 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f ccess..** ^If fo
12e30 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 r some reason, s
12e40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
12e50 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f e() is unable to
12e60 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 initialize.** t
12e70 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 he library (perh
12e80 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 aps it is unable
12e90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e to allocate a n
12ea0 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 eeded resource s
12eb0 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 uch.** as a mute
12ec0 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e x) it returns an
12ed0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 [error code] ot
12ee0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
12ef0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _OK]..**.** ^The
12f00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
12f10 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ize() routine is
12f20 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c called internal
12f30 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 ly by many other
12f40 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
12f50 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e faces so that an
12f60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 application usu
12f70 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 ally does not ne
12f80 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 ed to.** invoke
12f90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12fa0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 ze() directly.
12fb0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 For example, [sq
12fc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
12fd0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 calls sqlite3_i
12fe0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 nitialize() so t
12ff0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
13000 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 y will be automa
13010 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 tically.** initi
13020 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c alized when [sql
13030 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 ite3_open()] is
13040 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 called if it has
13050 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 not be initiali
13060 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 zed.** already.
13070 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 ^However, if SQ
13080 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
13090 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
130a0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
130b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
130c0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 option, then th
130d0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c e automatic call
130e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 s to sqlite3_ini
130f0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 tialize().** are
13100 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 omitted and the
13110 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
13120 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 t call sqlite3_i
13130 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
13140 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f ctly.** prior to
13150 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
13160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
13170 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 e. For maximum
13180 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 portability,.**
13190 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
131a0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
131b0 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b ons always invok
131c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
131d0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 lize().** direct
131e0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ly prior to usin
131f0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
13200 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
13210 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a uture releases.*
13220 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 * of SQLite may
13230 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 require this. I
13240 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
13250 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 he behavior exhi
13260 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 bited.** when SQ
13270 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
13280 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d with [SQLITE_OM
13290 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 IT_AUTOINIT] mig
132a0 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a ht become the.**
132b0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
132c0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 r in some future
132d0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
132e0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te..**.** The sq
132f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
13300 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 routine does ope
13310 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
13320 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 ecific.** initia
13330 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 lization of the
13340 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
13350 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
13360 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 end().** routine
13370 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
13380 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 ct of sqlite3_os
13390 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 _init(). Typica
133a0 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f l tasks.** perfo
133b0 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f rmed by these ro
133c0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 utines include a
133d0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 llocation or dea
133e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
133f0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 static resources
13400 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e , initialization
13410 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 of global varia
13420 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 bles,.** setting
13430 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 up a default [s
13440 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 qlite3_vfs] modu
13450 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 le, or setting u
13460 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 p.** a default c
13470 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 onfiguration usi
13480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ng [sqlite3_conf
13490 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ig()]..**.** The
134a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
134b0 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 uld never invoke
134c0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
134d0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 os_init().** or
134e0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
134f0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 directly. The
13500 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
13510 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a ld only invoke.*
13520 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 * sqlite3_initia
13530 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lize() and sqlit
13540 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
13550 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
13560 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 nit().** interfa
13570 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 ce is called aut
13580 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
13590 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
135a0 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
135b0 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 3_os_end() is ca
135c0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f lled by sqlite3_
135d0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 shutdown(). App
135e0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c ropriate.** impl
135f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
13600 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
13610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
13620 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 _end().** are bu
13630 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 ilt into SQLite
13640 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
13650 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 led for Unix, Wi
13660 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a ndows, or OS/2..
13670 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 ** When [custom
13680 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 builds | built f
13690 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 or other platfor
136a0 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 ms].** (using th
136b0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 e [SQLITE_OS_OTH
136c0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ER=1] compile-ti
136d0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 me.** option) th
136e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
136f0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 st supply a suit
13700 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
13710 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 ion for.** sqlit
13720 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
13730 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
13740 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 ). An applicati
13750 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 on-supplied.** i
13760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
13770 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
13780 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 () or sqlite3_os
13790 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 _end().** must r
137a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
137b0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
137c0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 some other [err
137d0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a or code] upon.**
137e0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c failure..*/.SQL
137f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
13800 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 te3_initialize(v
13810 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
13820 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 int sqlite3_shu
13830 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c tdown(void);.SQL
13840 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
13850 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 te3_os_init(void
13860 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
13870 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 t sqlite3_os_end
13880 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
13890 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
138a0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 ring The SQLite
138b0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 Library.**.** Th
138c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
138d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
138e0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
138f0 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
13900 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
13910 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
13920 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
13930 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
13940 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
13950 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
13960 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
13970 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
13980 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
13990 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
139a0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
139b0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
139c0 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
139d0 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
139e0 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
139f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
13a00 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
13a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
13a20 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
13a30 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
13a40 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
13a50 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
13a60 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
13a70 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
13a80 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
13a90 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
13aa0 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
13ab0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
13ac0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
13ad0 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
13ae0 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
13af0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
13b00 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
13b10 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
13b20 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
13b30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
13b40 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
13b50 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
13b60 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
13b70 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ^If sqlite3_conf
13b80 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 ig() is called a
13b90 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e fter [sqlite3_in
13ba0 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 itialize()] and
13bb0 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 before.** [sqlit
13bc0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 e3_shutdown()] t
13bd0 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 hen it will retu
13be0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 rn SQLITE_MISUSE
13bf0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 ..** Note, howev
13c00 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 er, that ^sqlite
13c10 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 3_config() can b
13c20 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 e called as part
13c30 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 of the.** imple
13c40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 mentation of an
13c50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
13c60 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f ned [sqlite3_os_
13c70 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 init()]..**.** T
13c80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
13c90 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e t to sqlite3_con
13ca0 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 fig() is an inte
13cb0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 ger.** [configur
13cc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 ation option] th
13cd0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a at determines.**
13ce0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f what property o
13cf0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 f SQLite is to b
13d00 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 e configured. S
13d10 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
13d20 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 nts.** vary depe
13d30 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f nding on the [co
13d40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13d50 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
13d60 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
13d70 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 .** ^When a conf
13d80 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13d90 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 is set, sqlite3
13da0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
13db0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
13dc0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e * ^If the option
13dd0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 is unknown or S
13de0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
13df0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f to set the optio
13e00 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 n.** then this r
13e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
13e20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
13e30 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 code]..*/.SQLIT
13e40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
13e50 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 3_config(int, ..
13e60 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
13e70 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 REF: Configure d
13e80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13e90 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ons.**.** The sq
13ea0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
13eb0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
13ec0 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 sed to make conf
13ed0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
13ee0 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 nges to a [datab
13ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
13f00 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 The interface
13f10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a is similar to.**
13f20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
13f30 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 ()] except that
13f40 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c the changes appl
13f50 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a y to a single.**
13f60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13f70 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 ction] (specifie
13f80 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
13f90 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 rgument)..**.**
13fa0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
13fb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
13fc0 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
13fd0 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ) is the.** [SQ
13fe0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
13ff0 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 OKASIDE | config
14000 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 uration verb] -
14010 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
14020 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 .** that indicat
14030 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f es what aspect o
14040 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
14050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
14060 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e eing configured.
14070 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 .** Subsequent a
14080 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 rguments vary de
14090 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
140a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
140b0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 b..**.** ^Calls
140c0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
140d0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 nfig() return SQ
140e0 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f LITE_OK if and o
140f0 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 nly if.** the ca
14100 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ll is considered
14110 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a successful..*/.
14120 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
14130 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
14140 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
14150 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
14160 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
14170 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
14180 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ines.**.** An in
14190 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
141a0 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
141b0 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
141c0 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e een SQLite.** an
141d0 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f d low-level memo
141e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
141f0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
14200 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 is object is use
14210 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c d in only one pl
14220 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ace in the SQLit
14230 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
14240 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
14250 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
14260 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 object is the a
14270 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 rgument to.** [s
14280 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
14290 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 when the config
142a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
142b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e s.** [SQLITE_CON
142c0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b FIG_MALLOC] or [
142d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
142e0 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 TMALLOC]. .** B
142f0 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e y creating an in
14300 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
14310 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 bject.** and pas
14320 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
14330 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
14340 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
14350 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f C]).** during co
14360 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 nfiguration, an
14370 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 application can
14380 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
14390 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
143a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
143b0 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 ystem for SQLite
143c0 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 to use for all
143d0 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 of its.** dynami
143e0 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a c memory needs..
143f0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
14400 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 SQLite comes wit
14410 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 h several [built
14420 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
14430 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 ators].** that a
14440 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 re perfectly ade
14450 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 quate for the ov
14460 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 erwhelming major
14470 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
14480 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ons.** and that
14490 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f this object is o
144a0 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 nly useful to a
144b0 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 tiny minority of
144c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
144d0 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 with specialize
144e0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
144f0 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 ion requirements
14500 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 . This object i
14510 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 s.** also used d
14520 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 uring testing of
14530 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
14540 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 to specify an a
14550 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
14560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
14570 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 hat simulates me
14580 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f mory out-of-memo
14590 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e ry conditions in
145a0 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 .** order to ver
145b0 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 ify that SQLite
145c0 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 recovers gracefu
145d0 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a lly from such.**
145e0 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a conditions..**.
145f0 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 ** The xMalloc,
14600 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 xRealloc, and xF
14610 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 ree methods must
14620 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
14630 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c * malloc(), real
14640 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
14650 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 functions from
14660 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
14670 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 ibrary..** ^SQLi
14680 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
14690 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 at the second ar
146a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 gument to.** xRe
146b0 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 alloc is always
146c0 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 a value returned
146d0 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c by a prior call
146e0 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a to xRoundup..**
146f0 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 .** xSize should
14700 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f return the allo
14710 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 cated size of a
14720 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14730 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 n.** previously
14740 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d obtained from xM
14750 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f alloc or xReallo
14760 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 c. The allocate
14770 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 d size.** is alw
14780 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 ays at least as
14790 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 big as the reque
147a0 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 sted size but ma
147b0 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a y be larger..**.
147c0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 ** The xRoundup
147d0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 method returns w
147e0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 hat would be the
147f0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
14800 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 of.** a memory a
14810 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 llocation given
14820 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 a particular req
14830 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f uested size. Mo
14840 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c st memory.** all
14850 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
14860 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
14870 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 ons at least to
14880 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c the next multipl
14890 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 e.** of 8. Some
148a0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
148b0 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 d up to a larger
148c0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 multiple or to
148d0 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a a power of 2..**
148e0 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c Every memory al
148f0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
14900 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 coming in throu
14910 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c gh [sqlite3_mall
14920 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c oc()].** or [sql
14930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
14940 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 first calls xRou
14950 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 ndup. If xRound
14960 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a up returns 0, .*
14970 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 * that causes th
14980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
14990 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
149a0 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a n to fail..**.**
149b0 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f The xInit metho
149c0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 d initializes th
149d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
149e0 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c or. (For exampl
149f0 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 e,.** it might a
14a00 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 llocate any requ
14a10 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 ire mutexes or i
14a20 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e nitialize intern
14a30 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 al data.** struc
14a40 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 tures. The xShu
14a50 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
14a60 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 invoked (indirec
14a70 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 tly) by.** [sqli
14a80 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
14a90 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c and should deall
14aa0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 ocate any resour
14ab0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 ces acquired.**
14ac0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 by xInit. The p
14ad0 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 AppData pointer
14ae0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f is used as the o
14af0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
14b00 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 .** xInit and xS
14b10 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 hutdown..**.** S
14b20 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 QLite holds the
14b30 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
14b40 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 ATIC_MASTER] mut
14b50 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b ex when it invok
14b60 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 es.** the xInit
14b70 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 method, so the x
14b80 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 Init method need
14b90 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 not be threadsa
14ba0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 fe. The.** xShu
14bb0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
14bc0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d only called from
14bd0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
14be0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 wn()] so it does
14bf0 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 .** not need to
14c00 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 be threadsafe ei
14c10 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f ther. For all o
14c20 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 ther methods, SQ
14c30 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 Lite.** holds th
14c40 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
14c50 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 STATIC_MEM] mute
14c60 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 x as long as the
14c70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
14c80 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f IG_MEMSTATUS] co
14c90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14ca0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 on is turned on
14cb0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 (which.** it is
14cc0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 by default) and
14cd0 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 so the methods a
14ce0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 re automatically
14cf0 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 serialized..**
14d00 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c However, if [SQL
14d10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
14d20 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 ATUS] is disable
14d30 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 d, then the othe
14d40 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 r.** methods mus
14d50 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 t be threadsafe
14d60 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 or else make the
14d70 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 ir own arrangeme
14d80 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 nts for.** seria
14d90 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 lization..**.**
14da0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
14db0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 r invoke xInit()
14dc0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 more than once
14dd0 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 without an inter
14de0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 vening.** call t
14df0 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a o xShutdown()..*
14e00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
14e10 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
14e20 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d hods sqlite3_mem
14e30 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
14e40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
14e50 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 hods {. void *(
14e60 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 *xMalloc)(int);
14e70 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 /* Memor
14e80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e y allocation fun
14e90 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
14ea0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b (*xFree)(void*);
14eb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 /* Fre
14ec0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 e a prior alloca
14ed0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
14ee0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 (*xRealloc)(void
14ef0 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 *,int); /* Resi
14f00 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e ze an allocation
14f10 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a */. int (*xSiz
14f20 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
14f30 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 /* Return t
14f40 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c he size of an al
14f50 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
14f60 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e t (*xRoundup)(in
14f70 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 t); /*
14f80 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 Round up request
14f90 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 size to allocat
14fa0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e ion size */. in
14fb0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a t (*xInit)(void*
14fc0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
14fd0 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d Initialize the m
14fe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
14ff0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 */. void (*xShu
15000 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 tdown)(void*);
15010 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c /* Deinitial
15020 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
15030 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
15040 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
15050 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
15060 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 Argument to xIni
15070 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 t() and xShutdow
15080 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a n() */.};../*.**
15090 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
150a0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
150b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
150c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
150d0 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion}.**.** These
150e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
150f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
15100 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
15110 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
15120 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
15130 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
15140 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
15150 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
15160 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
15170 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
15180 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
15190 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
151a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
151b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
151c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
151d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
151e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
151f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
15200 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
15210 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
15220 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 om [sqlite3_conf
15230 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
15240 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
15250 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
15260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
15270 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
15280 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
15290 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
152a0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
152b0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
152c0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
152d0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
152e0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
152f0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
15300 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
15310 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
15320 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
15330 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
15340 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
15350 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
15360 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
15370 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
15380 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
15390 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 de] to Single-th
153a0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 read. In other
153b0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c words, it disabl
153c0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 es.** all mutexi
153d0 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 ng and puts SQLi
153e0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 te into a mode w
153f0 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 here it can only
15400 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 be used.** by a
15410 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 single thread.
15420 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
15430 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
15440 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
15450 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
15460 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
15470 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15480 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
15490 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
154a0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 change the [thr
154b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f eading mode] fro
154c0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a m its default.**
154d0 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 value of Single
154e0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b -thread and so [
154f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
15500 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a ] will return .*
15510 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
15520 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
15530 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
15540 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a G_SINGLETHREAD.*
15550 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
15560 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
15570 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15580 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d IG_MULTITHREAD]]
15590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
155a0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f IG_MULTITHREAD</
155b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
155c0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
155d0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
155e0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
155f0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
15600 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
15610 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 Multi-thread. I
15620 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
15630 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 t disables.** mu
15640 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
15650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
15660 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
15670 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
15680 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
15690 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
156a0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
156b0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
156c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
156d0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
156e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
156f0 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
15700 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
15710 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
15720 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
15730 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
15740 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
15750 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
15760 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
15770 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
15780 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
15790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
157a0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
157b0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c e time. ^If SQL
157c0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
157d0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
157e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
157f0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
15800 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
15810 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
15820 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
15830 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 ible to set the
15840 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 Multi-thread [th
15850 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
15860 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
15870 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
15880 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
15890 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
158a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
158b0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
158c0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e AD configuration
158d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
158e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
158f0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d FIG_SERIALIZED]]
15900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15910 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 IG_SERIALIZED</d
15920 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
15930 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
15940 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
15950 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
15960 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
15970 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
15980 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 erialized. In ot
15990 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 her words, this
159a0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
159b0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
159c0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
159d0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
159e0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
159f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
15a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
15a10 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
15a20 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
15a30 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
15a40 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
15a50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
15a60 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
15a70 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
15a80 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
15a90 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
15aa0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
15ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
15ac0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
15ad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
15ae0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
15af0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
15b00 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
15b10 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
15b20 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
15b30 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
15b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
15b50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
15b60 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
15b70 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 me..** ^If SQLit
15b80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
15b90 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
15ba0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
15bb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15bc0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
15bd0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
15be0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
15bf0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 le to set the Se
15c00 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
15c10 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
15c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
15c30 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
15c40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
15c50 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
15c60 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
15c70 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f IG_SERIALIZED co
15c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15c90 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
15ca0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
15cb0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
15cc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
15cd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
15ce0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
15cf0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
15d00 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
15d10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
15d20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
15d30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
15d40 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
15d50 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
15d60 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
15d70 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
15d80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
15d90 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
15da0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
15db0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
15dc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
15dd0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
15de0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
15df0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 te makes.** its
15e00 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
15e10 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 of the content
15e20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
15e30 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
15e40 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 ucture.** before
15e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
15e60 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 nfig()] call ret
15e70 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a urns.</dd>.**.**
15e80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15e90 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 _GETMALLOC]] <dt
15ea0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
15eb0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
15ec0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
15ed0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
15ee0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
15ef0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
15f00 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
15f10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
15f20 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
15f30 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 ructure. The [s
15f40 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
15f50 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
15f60 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
15f70 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
15f80 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c fined memory all
15f90 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
15fa0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 .)^.** This opti
15fb0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
15fc0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
15fd0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
15fe0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
15ff0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
16000 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 per that simulat
16010 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ions memory allo
16020 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f cation failure o
16030 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f r.** tracks memo
16040 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 ry usage, for ex
16050 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a ample. </dd>.**.
16060 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16070 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c IG_MEMSTATUS]] <
16080 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
16090 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
160a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
160b0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
160c0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
160d0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
160e0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f ted as a .** boo
160f0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
16100 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
16110 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
16120 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
16130 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 ion .** statisti
16140 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
16150 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
16160 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
16170 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f bled, the .** fo
16180 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
16190 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
161a0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c non-operational
161b0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 :.** <ul>.**
161c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
161d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a emory_used()].**
161e0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
161f0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
16200 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b r()].** <li> [
16210 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
16220 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 p_limit64()].**
16230 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
16240 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c status()].** <
16250 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
16260 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
16270 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
16280 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
16290 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
162a0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
162b0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
162c0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
162d0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
162e0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
162f0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
16300 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
16310 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
16320 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16330 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 FIG_SCRATCH]] <d
16340 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
16350 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
16360 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
16370 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
16380 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
16390 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
163a0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 an use for.** sc
163b0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 ratch memory. T
163c0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
163d0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 rguments: A poi
163e0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
163f0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
16400 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
16410 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 ch the scratch a
16420 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 llocations will
16430 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 be.** drawn, the
16440 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
16450 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
16460 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
16470 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
16480 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f of scratch allo
16490 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 cations (N). Th
164a0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 e sz.** argument
164b0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 must be a multi
164c0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 ple of 16..** Th
164d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
164e0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 must be a point
164f0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 er to an 8-byte
16500 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a aligned buffer.*
16510 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a * of at least sz
16520 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
16530 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ry..** ^SQLite w
16540 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 ill use no more
16550 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 than two scratch
16560 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 buffers per thr
16570 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 ead. So.** N sh
16580 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 ould be set to t
16590 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 wice the expecte
165a0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 d maximum number
165b0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 of threads..**
165c0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 ^SQLite will nev
165d0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 er require a scr
165e0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 atch buffer that
165f0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a is more than 6.
16600 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 ** times the dat
16610 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
16620 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 ^If SQLite need
16630 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e s needs addition
16640 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 al.** scratch me
16650 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
16660 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
16670 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
16680 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
16690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
166a0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
166b0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
166c0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
166d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
166e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
166f0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
16700 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
16710 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
16720 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 ^This option sp
16730 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
16740 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
16750 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
16760 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 se for.** the da
16770 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 tabase page cach
16780 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 e with the defau
16790 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d lt page cache im
167a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
167b0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
167c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
167d0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
167e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
167f0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
16800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
16810 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
16820 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
16830 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e _PCACHE2 option.
16840 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 .** There are th
16850 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
16860 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 this option: A
16870 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 pointer to 8-byt
16880 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d e aligned.** mem
16890 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 ory, the size of
168a0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 each page buffe
168b0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
168c0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
168d0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 (N)..** The sz a
168e0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
168f0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 e the size of th
16900 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 e largest databa
16910 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f se page.** (a po
16920 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 wer of two betwe
16930 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 en 512 and 32768
16940 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 ) plus a little
16950 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a extra for each.*
16960 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 * page header.
16970 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 ^The page header
16980 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 size is 20 to 4
16990 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 0 bytes dependin
169a0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 g on.** the host
169b0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 architecture.
169c0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c ^It is harmless,
169d0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
169e0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
169f0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c * to make sz a l
16a00 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e ittle too large.
16a10 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
16a20 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
16a30 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
16a40 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
16a50 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
16a60 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
16a70 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
16a80 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
16a90 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
16aa0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
16ab0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
16ac0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
16ad0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
16ae0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
16af0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 . ^If additiona
16b00 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
16b10 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
16b20 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
16b30 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
16b40 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
16b50 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
16b60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
16b70 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
16b80 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
16b90 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ace..** The poin
16ba0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 ter in the first
16bb0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a argument must.*
16bc0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 * be aligned to
16bd0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
16be0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
16bf0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
16c00 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 ite.** will be u
16c10 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a ndefined.</dd>.*
16c20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16c30 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e NFIG_HEAP]] <dt>
16c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
16c50 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 AP</dt>.** <dd>
16c60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
16c70 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
16c80 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
16c90 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
16ca0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 se.** for all of
16cb0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
16cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
16cd0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 eeds beyond thos
16ce0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f e provided.** fo
16cf0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r by [SQLITE_CON
16d00 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
16d10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
16d20 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
16d30 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
16d40 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 rguments: An 8-b
16d50 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e yte aligned poin
16d60 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
16d70 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 y,.** the number
16d80 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
16d90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
16da0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
16db0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
16dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 .** ^If the firs
16dd0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
16de0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
16df0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
16e00 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
16e10 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
16e20 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
16e30 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
16e40 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
16e50 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
16e60 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
16e70 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
16e90 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a LOC]. ^If the.*
16ea0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 * memory pointer
16eb0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
16ec0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
16ed0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
16ee0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e or.** [SQLITE_EN
16ef0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 ABLE_MEMSYS5] ar
16f00 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 e defined, then
16f10 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
16f20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
16f30 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
16f40 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
16f50 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
16f60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
16f70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f .** The first po
16f80 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
16f90 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 y pointer) must
16fa0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
16fb0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 8-byte.** bound
16fc0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e ary or subsequen
16fd0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 t behavior of SQ
16fe0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 Lite will be und
16ff0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d efined..** The m
17000 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
17010 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 n size is capped
17020 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f at 2**12. Reaso
17030 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 nable values.**
17040 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 for the minimum
17050 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
17060 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 are 2**5 through
17070 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2**8.</dd>.**.*
17080 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17090 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 G_MUTEX]] <dt>SQ
170a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
170b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
170c0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
170d0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
170e0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
170f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
17100 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
17110 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
17120 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
17130 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
17140 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
17150 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
17160 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
17170 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
17180 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d n place.** the m
17190 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
171a0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
171b0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
171c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
171d0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 ** content of th
171e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
171f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
17200 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 ure before the c
17210 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
17220 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 e3_config()] ret
17230 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 urns. ^If SQLite
17240 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
17250 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
17260 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
17270 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
17280 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
17290 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
172a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
172b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
172c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
172d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
172e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
172f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
17300 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
17310 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e CONFIG_MUTEX con
17320 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
17330 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
17340 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
17350 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
17360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
17370 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
17380 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
17390 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
173a0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
173b0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
173c0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
173d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
173e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
173f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
17400 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
17410 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
17420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
17430 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
17440 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
17450 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
17460 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
17470 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
17480 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
17490 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
174a0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
174b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
174c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
174d0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
174e0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
174f0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
17500 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
17510 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
17520 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c ample. ^If SQL
17530 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
17540 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
17550 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
17560 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
17570 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
17580 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
17590 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
175a0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
175b0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
175c0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
175d0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
175e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
175f0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
17600 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
17610 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
17620 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
17630 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
17640 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
17650 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17660 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 G_LOOKASIDE]] <d
17670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17680 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
17690 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
176a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
176b0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
176c0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 termine the defa
176d0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ult.** memory al
176e0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 location for the
176f0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
17700 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 y allocator on e
17710 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ach.** [database
17720 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
17730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
17740 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
17750 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
17760 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
17770 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
17780 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
17790 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
177a0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e se connection.)^
177c0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 ^(This option
177d0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 sets the.** <i>d
177e0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 efault</i> looka
177f0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b side size. The [
17800 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
17810 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 LOOKASIDE].** ve
17820 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 rb to [sqlite3_d
17830 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 b_config()] can
17840 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 be used to chang
17850 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
17860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
17870 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 on individual c
17880 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f onnections.)^ </
17890 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
178a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
178b0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
178c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 ONFIG_PCACHE2</d
178d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
178e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
178f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
17900 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
17910 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 ter to.** an [sq
17920 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
17930 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
17940 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
17950 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
17960 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
17970 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
17980 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 plementation.)^
17990 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
179a0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
179b0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 object and uses
179c0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 it for page cach
179d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
179e0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ions.</dd>.**.**
179f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
17a00 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 _GETPCACHE2]] <d
17a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17a20 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a GETPCACHE2</dt>.
17a30 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
17a40 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
17a50 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
17a60 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
17a70 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
17a80 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
17a90 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c s2] object. SQL
17aa0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 ite copies of th
17ab0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 e current.** pag
17ac0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
17ad0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 tation into that
17ae0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e object.)^ </dd>
17af0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
17b00 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 CONFIG_LOG]] <dt
17b10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
17b20 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OG</dt>.** <dd>
17b30 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
17b40 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
17b50 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
17b60 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
17b70 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
17b80 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
17b90 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
17ba0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
17bb0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
17bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
17bd0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
17be0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
17bf0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
17c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
17c10 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
17c20 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
17c30 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
17c40 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
17c50 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
17c60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
17c70 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
17c80 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
17c90 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
17ca0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
17cb0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
17cc0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
17cd0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
17ce0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
17cf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
17d00 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
17d10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
17d20 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
17d30 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
17d40 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
17d50 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
17d60 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
17d70 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
17d80 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
17d90 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
17da0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
17db0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
17dc0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
17dd0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
17de0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
17df0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
17e00 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
17e10 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
17e20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
17e30 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
17e40 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
17e50 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
17e60 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
17e70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
17e80 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
17e90 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
17ea0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
17eb0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
17ec0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
17ed0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
17ee0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
17ef0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
17f00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
17f10 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
17f20 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
17f30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
17f40 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
17f50 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
17f60 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
17f70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
17f80 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d ITE_CONFIG_URI]]
17f90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17fa0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 IG_URI.** <dd> T
17fb0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
17fc0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
17fd0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 nt of type int.
17fe0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 If non-zero, the
17ff0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e n.** URI handlin
18000 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
18010 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
18020 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
18030 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
18040 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c ng.** is globall
18050 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 y disabled. If U
18060 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
18070 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c lobally enabled,
18080 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a all filenames.*
18090 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c * passed to [sql
180a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
180b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
180c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
180d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 16()] or.** spec
180e0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 ified as part of
180f0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e [ATTACH] comman
18100 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 ds are interpret
18110 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 ed as URIs, rega
18120 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 rdless.** of whe
18130 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
18140 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
18150 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 ] flag is set wh
18160 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a en the database.
18170 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
18180 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 opened. If it i
18190 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
181a0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 led, filenames a
181b0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 re.** only inter
181c0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 preted as URIs i
181d0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 f the SQLITE_OPE
181e0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 N_URI flag is se
181f0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 t when the.** da
18200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18210 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 n is opened. By
18220 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e default, URI han
18230 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
18240 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 y.** disabled. T
18250 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
18260 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 may be changed
18270 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 by compiling wit
18280 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
18290 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c _USE_URI] symbol
182a0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
182b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
182c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
182d0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CAN]] <dt>SQLITE
182e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
182f0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c _INDEX_SCAN.** <
18300 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 dd> This option
18310 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 takes a single i
18320 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 nteger argument
18330 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 which is interpr
18340 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f eted as.** a boo
18350 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f lean in order to
18360 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
18370 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
18380 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
18390 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 or.** full table
183a0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 scans in the qu
183b0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 ery optimizer.
183c0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
183d0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 ing is determine
183e0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c d.** by the [SQL
183f0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 ITE_ALLOW_COVERI
18400 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 NG_INDEX_SCAN] c
18410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
18420 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a on, or is "on".*
18430 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c * if that compil
18440 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
18450 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 omitted..** The
18460 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 ability to disa
18470 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 ble the use of c
18480 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
18490 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
184a0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 cans.** is becau
184b0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 se some incorrec
184c0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 tly coded legacy
184d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 applications mi
184e0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a ght malfunction.
184f0 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 ** malfunction w
18500 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 hen the optimiza
18510 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
18520 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 Providing the
18530 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 ability to.** di
18540 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 sable the optimi
18550 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 zation allows th
18560 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 e older, buggy a
18570 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
18580 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f to work.** witho
18590 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 ut change even w
185a0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f ith newer versio
185b0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
185c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
185d0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 FIG_PCACHE]] [[S
185e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
185f0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e PCACHE]].** <dt>
18600 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
18610 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f ACHE and SQLITE_
18620 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
18630 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f .** <dd> These o
18640 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c ptions are obsol
18650 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e ete and should n
18660 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 ot be used by ne
18670 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 w code..** They
18680 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
18690 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
186a0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 tibility but are
186b0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 now no-ops..**
186c0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dl>.**.** [[SQ
186d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
186e0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 OG]].** <dt>SQLI
186f0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
18700 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
18710 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
18720 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 lable if sqlite
18730 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
18740 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 the.** SQLITE_E
18750 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 NABLE_SQLLOG pre
18760 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
18770 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
18780 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
18790 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
187a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
187b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
187c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
187d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
187e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
187f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
18800 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
18810 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
18820 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
18830 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
18840 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
18850 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
18860 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
18870 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
18880 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
18890 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
188a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
188b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
188c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
188d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
188e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
188f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
18900 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
18910 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
18920 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
18930 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
18940 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
18950 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
18960 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
18970 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
18980 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
18990 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
189a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
189b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
189c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
189d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
189e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
189f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
18a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
18a10 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
18a20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18a30 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
18a40 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
18a50 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
18a60 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
18a70 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a case..** </dl>.*
18a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18a90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
18aa0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
18ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18ac0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
18ad0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
18ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18af0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
18b00 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
18b10 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
18b20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
18b30 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
18b40 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
18b50 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
18b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
18b70 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
18b80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
18b90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
18ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18bb0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
18bc0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
18bd0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18bf0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
18c00 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
18c10 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
18c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18c30 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
18c40 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
18c50 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
18c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18c70 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
18c80 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
18c90 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
18ca0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
18cb0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
18cc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
18cd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
18ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
18cf0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
18d00 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
18d10 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
18d20 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
18d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
18d40 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
18d50 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
18d60 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
18d70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
18d80 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
18d90 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
18da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
18db0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
18dc0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
18dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18de0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
18df0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
18e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18e10 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
18e20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
18e30 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
18e40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
18e50 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
18e60 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
18e70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18e80 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
18e90 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
18ea0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
18eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18ec0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
18ed0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
18ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
18ef0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
18f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
18f10 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
18f20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 20 /* int */.#d
18f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18f40 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 FIG_SQLLOG
18f50 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 21 /* xSqllog,
18f60 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a void* */../*.**
18f70 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
18f80 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 ase Connection C
18f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
18fa0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
18fb0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
18fc0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
18fd0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
18fe0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
18ff0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
19000 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
19010 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
19020 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
19030 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
19040 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
19050 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
19060 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
19070 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
19080 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
19090 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
190a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
190b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
190c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
190d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
190e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
190f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
19100 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 db_config()] to
19110 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a make sure that.*
19120 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 * the call worke
19130 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 d. ^The [sqlite
19140 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 3_db_config()] i
19150 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
19160 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
19170 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
19180 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
19190 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
191a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
191b0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
191c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
191d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
191e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
191f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
19200 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
19210 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 three additiona
19220 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 l arguments that
19230 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a determine the .
19240 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ** [lookaside me
19250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 mory allocator]
19260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
19270 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 r the [database
19280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 connection]..**
19290 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
192a0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 ent (the third p
192b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
192c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
192d0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 ] is a.** pointe
192e0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 r to a memory bu
192f0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 ffer to use for
19300 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
19310 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
19320 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 argument after t
19330 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 he SQLITE_DBCONF
19340 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 IG_LOOKASIDE ver
19350 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c b.** may be NULL
19360 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 in which case S
19370 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 QLite will alloc
19380 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 ate the.** looka
19390 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 side buffer itse
193a0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 lf using [sqlite
193b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 3_malloc()]. ^Th
193c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
193d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
193e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
193f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 de buffer slot.
19400 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 ^The third argu
19410 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 ment is the numb
19420 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 er of.** slots.
19430 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 The size of the
19440 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 buffer in the f
19450 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
19460 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 st be greater th
19470 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 an.** or equal t
19480 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 o the product of
19490 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
194a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e third arguments.
194b0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 The buffer.**
194c0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 must be aligned
194d0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 to an 8-byte bou
194e0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 ndary. ^If the
194f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
19500 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 to.** SQLITE_DBC
19510 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
19520 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c is not a multipl
19530 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e e of 8, it is in
19540 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e ternally.** roun
19550 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 ded down to the
19560 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c next smaller mul
19570 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 tiple of 8. ^(T
19580 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d he lookaside mem
19590 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ory.** configura
195a0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 tion for a datab
195b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
195c0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 an only be chang
195d0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 ed when that.**
195e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f connection is no
195f0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e t currently usin
19600 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f g lookaside memo
19610 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 ry, or in other
19620 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 words.** when th
19630 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 e "current value
19640 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a " returned by.**
19650 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 [sqlite3_db_sta
19660 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 tus](D,[SQLITE_C
19670 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
19680 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a ,...) is zero..*
19690 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f * Any attempt to
196a0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
196b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e aside memory con
196c0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 figuration when
196d0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d lookaside.** mem
196e0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 ory is in use le
196f0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 aves the configu
19700 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 ration unchanged
19710 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a and returns .**
19720 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 [SQLITE_BUSY].)
19730 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 ^</dd>.**.** <dt
19740 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
19750 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 _ENABLE_FKEY</dt
19760 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
19770 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
19780 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
19790 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d ble the enforcem
197a0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 ent of.** [forei
197b0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e gn key constrain
197c0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 ts]. There shou
197d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
197e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
197f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
19800 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
19810 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
19820 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 o disable FK enf
19830 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 orcement,.** pos
19840 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
19850 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f FK enforcement o
19860 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
19870 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 ave FK enforceme
19880 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e nt.** unchanged.
19890 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
198a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
198b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
198c0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
198d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
198e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
198f0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 ether FK enforce
19900 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f ment is off or o
19910 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 n.** following t
19920 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
19930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
19940 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
19950 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
19960 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 ch case the FK e
19970 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 nforcement setti
19980 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
19990 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
199a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
199b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
199c0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 TRIGGER</dt>.**
199d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
199e0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
199f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b ble or disable [
19a00 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
19a10 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 triggers]..** T
19a20 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
19a30 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
19a40 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
19a50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
19a60 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
19a70 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
19a80 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 le triggers,.**
19a90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
19aa0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e le triggers or n
19ab0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 egative to leave
19ac0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 the setting unc
19ad0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 hanged..** The s
19ae0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
19af0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
19b00 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
19b10 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
19b20 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
19b30 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 dicate whether t
19b40 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 riggers are disa
19b50 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a bled or enabled.
19b60 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
19b70 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
19b80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
19b90 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
19ba0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
19bb0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 case the trigge
19bc0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 r setting is not
19bd0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
19be0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c </dd>.**.** </dl
19bf0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
19c00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
19c10 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 KASIDE 100
19c20 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 1 /* void* int
19c30 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
19c40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
19c50 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 NABLE_FKEY 1
19c60 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 002 /* int int*
19c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19c80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19c90 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 LE_TRIGGER 1003
19ca0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f /* int int* */
19cb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
19cc0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
19cd0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 able Extended Re
19ce0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a sult Codes.**.**
19cf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
19d00 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
19d10 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e des() routine en
19d20 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
19d30 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 s the.** [extend
19d40 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
19d50 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 feature of SQLi
19d60 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 te. ^The extende
19d70 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 d result.** code
19d80 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
19d90 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 y default for hi
19da0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
19db0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 bility..*/.SQLIT
19dc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
19dd0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
19de0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a t_codes(sqlite3*
19df0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f , int onoff);../
19e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
19e10 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 ast Insert Rowid
19e20 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 .**.** ^Each ent
19e30 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 ry in an SQLite
19e40 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 table has a uniq
19e50 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
19e60 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
19e70 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
19e80 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
19e90 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
19ea0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
19eb0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
19ec0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
19ed0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
19ee0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
19ef0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
19f00 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
19f10 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
19f20 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
19f30 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
19f40 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
19f50 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
19f60 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
19f70 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
19f80 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
19f90 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
19fa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
19fb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
19fc0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
19fd0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 most recent.** s
19fe0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
19ff0 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 T] into the data
1a000 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 base from the [d
1a010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a020 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 on].** in the fi
1a030 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e rst argument. ^
1a040 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 As of SQLite ver
1a050 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 sion 3.7.7, this
1a060 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 routines.** rec
1a070 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e ords the last in
1a080 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f sert rowid of bo
1a090 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c th ordinary tabl
1a0a0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 es and [virtual
1a0b0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 tables]..** ^If
1a0c0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 no successful [I
1a0d0 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 NSERT]s.** have
1a0e0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e ever occurred on
1a0f0 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 that database c
1a100 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 onnection, zero
1a110 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1a120 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 ** ^(If an [INSE
1a130 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 RT] occurs withi
1a140 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 n a trigger or w
1a150 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c ithin a [virtual
1a160 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f table].** metho
1a170 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 d, then this rou
1a180 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e tine will return
1a190 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 the [rowid] of
1a1a0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 the inserted.**
1a1b0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 row as long as t
1a1c0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
1a1d0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
1a1e0 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a od is running..*
1a1f0 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 * But once the t
1a200 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
1a210 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 l table method e
1a220 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 nds, the value r
1a230 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 eturned .** by t
1a240 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 his routine reve
1a250 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 rts to what it w
1a260 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 as before the tr
1a270 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
1a280 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 .** table method
1a290 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 began.)^.**.**
1a2a0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 ^An [INSERT] tha
1a2b0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 t fails due to a
1a2c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
1a2d0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a ation is not a.*
1a2e0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e * successful [IN
1a2f0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e SERT] and does n
1a300 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
1a310 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1a320 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
1a330 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f ^Thus INSERT O
1a340 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f R FAIL, INSERT O
1a350 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 R IGNORE, INSERT
1a360 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a OR ROLLBACK,.**
1a370 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 and INSERT OR A
1a380 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 BORT make no cha
1a390 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 nges to the retu
1a3a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
1a3b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e .** routine when
1a3c0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e their insertion
1a3d0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 fails. ^(When
1a3e0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
1a3f0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 E.** encounters
1a400 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
1a410 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 lation, it does
1a420 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a not fail. The.*
1a430 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 * INSERT continu
1a440 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e es to completion
1a450 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 after deleting
1a460 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 rows that caused
1a470 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 .** the constrai
1a480 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e nt problem so IN
1a490 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 SERT OR REPLACE
1a4a0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e will always chan
1a4b0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e ge.** the return
1a4c0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 value of this i
1a4d0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a nterface.)^.**.*
1a4e0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f * ^For the purpo
1a4f0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
1a500 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d ine, an [INSERT]
1a510 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 is considered t
1a520 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 o.** be successf
1a530 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 ul even if it is
1a540 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f subsequently ro
1a550 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a lled back..**.**
1a560 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 This function i
1a570 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 s accessible to
1a580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 SQL statements v
1a590 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f ia the.** [last_
1a5a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 insert_rowid() S
1a5b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1a5c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1a5d0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d e thread perform
1a5e0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d s a new [INSERT]
1a5f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 on the same.**
1a600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a610 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 ion while the [s
1a620 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
1a630 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 rt_rowid()].** f
1a640 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
1a650 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e ng and thus chan
1a660 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 ges the last ins
1a670 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 ert [rowid],.**
1a680 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 then the value r
1a690 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1a6a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
1a6b0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 rowid()] is.** u
1a6c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
1a6d0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c might not equal
1a6e0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 either the old
1a6f0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 or the new.** la
1a700 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
1a710 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1a720 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
1a730 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
1a740 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
1a750 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1a760 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
1a770 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
1a780 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
1a790 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
1a7a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1a7b0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 f database rows
1a7c0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 that were change
1a7d0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 d.** or inserted
1a7e0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 or deleted by t
1a7f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
1a800 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 completed SQL s
1a810 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 tatement.** on t
1a820 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1a830 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
1a840 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
1a850 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 parameter..** ^(
1a860 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 Only changes tha
1a870 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 t are directly s
1a880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
1a890 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 [INSERT], [UPDAT
1a8a0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 E],.** or [DELET
1a8b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 E] statement are
1a8c0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
1a8d0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
1a8e0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
1a8f0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b rs or [foreign k
1a900 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 ey actions] are
1a910 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 not counted.)^ U
1a920 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 se the.** [sqlit
1a930 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1a940 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ()] function to
1a950 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
1a960 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
1a970 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 .** including ch
1a980 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
1a990 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 triggers and for
1a9a0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
1a9b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 ..**.** ^Changes
1a9c0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
1a9d0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 are simulated by
1a9e0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
1a9f0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 trigger].** are
1aa00 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e not counted. On
1aa10 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 ly real table ch
1aa20 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 anges are counte
1aa30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f d..**.** ^(A "ro
1aa40 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
1aa50 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
1aa60 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
1aa70 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
1aa80 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
1aa90 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
1aaa0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
1aab0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
1aac0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
1aad0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 ffects of [REPLA
1aae0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 CE] constraint r
1aaf0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
1ab00 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
1ab10 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 ocessing, [DROP
1ab20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e TABLE], or by an
1ab30 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 y other.** mecha
1ab40 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 nisms do not cou
1ab50 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 nt as direct row
1ab60 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a changes.)^.**.*
1ab70 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
1ab80 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
1ab90 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
1aba0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
1abb0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
1abc0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 cript of a [CREA
1abd0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
1abe0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 gger]. .** Most
1abf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
1ac00 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 re.** evaluated
1ac10 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 outside of any t
1ac20 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 rigger. This is
1ac30 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 the "top level"
1ac40 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
1ac50 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 ext. If a trigg
1ac60 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 er fires from th
1ac70 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a e top level, a.*
1ac80 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f * new trigger co
1ac90 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 ntext is entered
1aca0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f for the duratio
1acb0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a n of that one.**
1acc0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 trigger. Subtr
1acd0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 iggers create su
1ace0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 bcontexts for th
1acf0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a eir duration..**
1ad00 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 .** ^Calling [sq
1ad10 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 lite3_exec()] or
1ad20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1ad30 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f ] recursively do
1ad40 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 es.** not create
1ad50 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 a new trigger c
1ad60 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ontext..**.** ^T
1ad70 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
1ad80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
1ad90 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 of direct row ch
1ada0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 anges in the.**
1adb0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 most recent INSE
1adc0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
1add0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1ade0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a within the same.
1adf0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
1ae00 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c xt..**.** ^Thus,
1ae10 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f when called fro
1ae20 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
1ae30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
1ae40 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 eturns the.** nu
1ae50 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 mber of changes
1ae60 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 in the most rece
1ae70 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
1ae80 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
1ae90 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 that also occurr
1aea0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 ed at the top le
1aeb0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 vel. ^(Within t
1aec0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 he body of a tri
1aed0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c gger,.** the sql
1aee0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 ite3_changes() i
1aef0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
1af00 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 called to find t
1af10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1af20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
1af30 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
1af40 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
1af50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
1af60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 .** statement wi
1af70 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
1af80 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
1af90 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 r..** However, t
1afa0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e he number return
1afb0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ed does not incl
1afc0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 ude changes.** c
1afd0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 aused by subtrig
1afe0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 gers since those
1aff0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 have their own
1b000 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a context.)^.**.**
1b010 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
1b020 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1b030 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
1b040 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
1b050 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
1b060 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
1b070 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
1b080 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
1b090 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
1b0a0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
1b0b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
1b0c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1b0d0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
1b0e0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1b0f0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1b100 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
1b110 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1b120 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1b130 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
1b140 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1b150 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
1b160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1b170 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
1b180 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
1b190 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
1b1a0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
1b1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 e number of row
1b1c0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
1b1d0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b y [INSERT],.** [
1b1e0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 UPDATE] or [DELE
1b1f0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 TE] statements s
1b200 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 ince the [databa
1b210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
1b220 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 as opened..** ^(
1b230 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e The count return
1b240 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f ed by sqlite3_to
1b250 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e tal_changes() in
1b260 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 cludes all chang
1b270 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b es.** from all [
1b280 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
1b290 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 trigger] contex
1b2a0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d ts and changes m
1b2b0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 ade by.** [forei
1b2c0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e gn key actions].
1b2d0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
1b2e0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
1b2f0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
1b300 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
1b310 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 t [REPLACE] cons
1b320 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 traints,.** do r
1b330 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 ollbacks or ABOR
1b340 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 T processing, or
1b350 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 [DROP TABLE] pr
1b360 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a ocessing. The.*
1b370 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 * count does not
1b380 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 include rows of
1b390 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 views that fire
1b3a0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 an [INSTEAD OF
1b3b0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f trigger],.** tho
1b3c0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 ugh if the INSTE
1b3d0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 AD OF trigger ma
1b3e0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 kes changes of i
1b3f0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 ts own, those ch
1b400 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f anges .** are co
1b410 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 unted.)^.** ^The
1b420 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
1b430 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f hanges() functio
1b440 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 n counts the cha
1b450 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a nges as soon as.
1b460 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
1b470 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
1b480 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 is completed (w
1b490 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
1b4a0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 t handle.** is p
1b4b0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
1b4c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
1b4d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
1b4e0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 )])..**.** See a
1b4f0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
1b500 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
1b510 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
1b520 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
1b530 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 gma], and the [t
1b540 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 otal_changes() S
1b550 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1b560 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1b570 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1b580 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1b590 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1b5a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1b5b0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
1b5c0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1b5d0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1b5e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1b5f0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1b600 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1b610 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
1b620 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
1b630 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
1b640 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1b650 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
1b660 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
1b670 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 g Query.**.** ^T
1b680 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
1b690 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
1b6a0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
1b6b0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
1b6c0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
1b6d0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
1b6e0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
1b6f0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
1b700 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
1b710 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
1b720 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
1b730 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
1b740 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
1b750 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
1b760 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
1b770 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
1b780 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
1b790 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
1b7a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
1b7b0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
1b7c0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
1b7d0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
1b7e0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
1b7f0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
1b800 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
1b810 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
1b820 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
1b830 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
1b840 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
1b850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1b860 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
1b870 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
1b880 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
1b890 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
1b8a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
1b8b0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
1b8c0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
1b8d0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
1b8e0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
1b8f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1b900 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
1b910 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
1b920 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
1b930 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
1b940 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
1b950 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
1b960 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
1b970 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
1b980 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
1b990 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
1b9a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
1b9b0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
1b9c0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
1b9d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
1b9e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
1b9f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
1ba00 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
1ba10 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
1ba20 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
1ba30 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
1ba40 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
1ba50 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
1ba60 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
1ba70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1ba80 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
1ba90 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
1baa0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
1bab0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
1bac0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
1bad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
1bae0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
1baf0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
1bb00 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
1bb10 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
1bb20 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1bb30 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
1bb40 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
1bb50 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
1bb60 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
1bb70 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
1bb80 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
1bb90 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
1bba0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
1bbb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
1bbc0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
1bbd0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1bbe0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1bbf0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
1bc00 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
1bc10 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
1bc20 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
1bc30 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
1bc40 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
1bc50 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
1bc60 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
1bc70 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
1bc80 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
1bc90 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
1bca0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
1bcb0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
1bcc0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
1bcd0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
1bce0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
1bcf0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
1bd00 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
1bd10 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
1bd20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1bd30 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
1bd40 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
1bd50 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
1bd60 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
1bd70 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
1bd80 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 ely happen..*/.S
1bd90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
1bda0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1bdb0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1bdc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
1bdd0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
1bde0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
1bdf0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
1be00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
1be10 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
1be20 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
1be30 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
1be40 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
1be50 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
1be60 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
1be70 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1be80 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
1be90 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
1bea0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
1beb0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
1bec0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
1bed0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
1bee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1bef0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
1bf00 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
1bf10 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
1bf20 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1bf30 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
1bf40 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
1bf50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
1bf60 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
1bf70 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
1bf80 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
1bf90 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
1bfa0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
1bfb0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
1bfc0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
1bfd0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
1bfe0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
1bff0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
1c000 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
1c010 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
1c020 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
1c030 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
1c040 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
1c050 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
1c060 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
1c070 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
1c080 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
1c090 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
1c0a0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
1c0b0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
1c0c0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
1c0d0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
1c0e0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
1c0f0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
1c100 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1c110 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
1c120 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
1c130 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
1c140 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
1c150 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
1c160 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
1c170 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1c180 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1c190 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
1c1a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1c1b0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
1c1c0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
1c1d0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
1c1e0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
1c1f0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
1c200 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
1c210 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
1c220 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
1c230 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
1c240 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
1c250 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
1c260 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1c270 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
1c280 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
1c290 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1c2a0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
1c2b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
1c2c0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
1c2d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1c2e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
1c2f0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
1c300 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
1c310 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
1c320 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
1c330 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
1c340 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
1c350 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
1c360 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
1c370 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
1c380 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
1c390 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
1c3a0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1c3b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1c3c0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1c3d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1c3e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
1c3f0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
1c400 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 der..*/.SQLITE_A
1c410 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1c420 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 omplete(const ch
1c430 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 ar *sql);.SQLITE
1c440 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1c450 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
1c460 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
1c470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1c480 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
1c490 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
1c4a0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
1c4b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1c4c0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
1c4d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
1c4e0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
1c4f0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
1c500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
1c510 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
1c520 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
1c530 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
1c540 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
1c550 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
1c560 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
1c570 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
1c580 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
1c590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1c5a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
1c5b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
1c5c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
1c5d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
1c5e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
1c5f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
1c600 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
1c610 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
1c620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
1c630 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
1c640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
1c650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1c660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1c670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
1c680 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
1c690 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
1c6a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
1c6b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1c6c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
1c6d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
1c6e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
1c6f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
1c700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
1c710 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
1c720 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
1c730 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
1c740 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
1c750 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
1c760 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
1c770 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
1c780 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
1c790 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
1c7a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
1c7b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
1c7c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
1c7d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
1c7e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
1c7f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
1c800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1c810 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
1c820 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
1c830 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
1c840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
1c850 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
1c860 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
1c870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
1c880 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
1c890 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
1c8a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
1c8b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
1c8c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
1c8d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
1c8e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
1c8f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
1c900 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
1c910 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
1c920 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
1c930 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
1c940 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
1c950 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
1c960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
1c970 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
1c980 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
1c990 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
1c9a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
1c9b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
1c9c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
1c9d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
1c9e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
1c9f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
1ca00 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
1ca10 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
1ca20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
1ca30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
1ca40 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
1ca50 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
1ca60 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
1ca70 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
1ca80 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
1ca90 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
1caa0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
1cab0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1cac0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
1cad0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1cae0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
1caf0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
1cb00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
1cb10 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
1cb20 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
1cb30 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
1cb40 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
1cb50 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
1cb60 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
1cb70 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
1cb80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
1cb90 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
1cba0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
1cbb0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
1cbc0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
1cbd0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
1cbe0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
1cbf0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
1cc00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1cc10 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
1cc20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
1cc30 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
1cc40 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
1cc50 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
1cc60 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
1cc70 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
1cc80 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
1cc90 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
1cca0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
1ccb0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
1ccc0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
1ccd0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
1cce0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
1ccf0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
1cd00 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
1cd10 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
1cd20 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
1cd30 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
1cd40 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
1cd50 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
1cd60 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
1cd70 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
1cd80 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
1cd90 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
1cda0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
1cdb0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
1cdc0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
1cdd0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
1cde0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
1cdf0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
1ce00 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
1ce10 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
1ce20 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
1ce30 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
1ce40 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
1ce50 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
1ce60 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
1ce70 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
1ce80 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
1ce90 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
1cea0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
1ceb0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
1cec0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
1ced0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
1cee0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
1cef0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
1cf00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
1cf10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
1cf20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
1cf30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
1cf40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
1cf50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
1cf60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
1cf70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
1cf80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
1cf90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
1cfa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
1cfb0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
1cfc0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
1cfd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
1cfe0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
1cff0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1d000 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
1d010 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
1d020 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
1d030 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
1d040 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
1d050 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
1d060 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1d070 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
1d080 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
1d090 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
1d0a0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
1d0b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
1d0c0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
1d0d0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
1d0e0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d100 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1d110 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1d120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
1d130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
1d140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
1d150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
1d160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
1d170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
1d180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1d190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
1d1a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
1d1b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
1d1c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 sy handler..*/.S
1d1d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1d1e0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1d1f0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
1d200 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
1d210 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1d220 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
1d230 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a usy Timeout.**.*
1d240 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
1d250 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
1d260 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
1d270 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
1d280 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
1d290 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
1d2a0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
1d2b0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
1d2c0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 d. ^The handler
1d2d0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d .** will sleep m
1d2e0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
1d2f0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 til at least "ms
1d300 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f " milliseconds o
1d310 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 f sleeping.** ha
1d320 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 ve accumulated.
1d330 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 ^After at least
1d340 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1d350 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a ds of sleeping,.
1d360 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 ** the handler r
1d370 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 eturns 0 which c
1d380 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 auses [sqlite3_s
1d390 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e tep()] to return
1d3a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
1d3b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
1d3c0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a RR_BLOCKED]..**.
1d3d0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
1d3e0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
1d3f0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
1d400 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
1d410 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
1d420 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
1d430 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
1d440 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
1d450 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
1d460 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
1d470 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1d480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
1d490 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d ny any given mom
1d4a0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
1d4b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
1d4c0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
1d4d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
1d4e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
1d4f0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
1d500 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
1d510 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
1d520 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
1d530 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 red.)^.*/.SQLITE
1d540 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1d550 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
1d560 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
1d570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1d580 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
1d590 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
1d5a0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a ng Queries.**.**
1d5b0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 This is a legac
1d5c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 y interface that
1d5d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f is preserved fo
1d5e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
1d5f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 atibility..** Us
1d600 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
1d610 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d ace is not recom
1d620 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 mended..**.** De
1d630 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 finition: A <b>r
1d640 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 esult table</b>
1d650 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 is memory data s
1d660 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 tructure created
1d670 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 by the.** [sqli
1d680 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
1d690 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 interface. A r
1d6a0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f esult table reco
1d6b0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c rds the.** compl
1d6c0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 ete query result
1d6d0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f s from one or mo
1d6e0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a re queries..**.*
1d6f0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 * The table conc
1d700 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e eptually has a n
1d710 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e umber of rows an
1d720 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a d columns. But.
1d730 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 ** these numbers
1d740 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 are not part of
1d750 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1d760 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 e itself. These
1d770 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 .** numbers are
1d780 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 obtained separat
1d790 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 ely. Let N be t
1d7a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
1d7b0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 s.** and M be th
1d7c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1d7d0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 mns..**.** A res
1d7e0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 ult table is an
1d7f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 array of pointer
1d800 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e s to zero-termin
1d810 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e ated UTF-8 strin
1d820 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 gs..** There are
1d830 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 (N+1)*M element
1d840 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 s in the array.
1d850 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 The first M poi
1d860 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 nters point.** t
1d870 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1d880 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 d strings that
1d890 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 contain the name
1d8a0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 s of the columns
1d8b0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 ..** The remaini
1d8c0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 ng entries all p
1d8d0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 oint to query re
1d8e0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c sults. NULL val
1d8f0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e ues result.** in
1d900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 NULL pointers.
1d910 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 All other value
1d920 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 s are in their U
1d930 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e TF-8 zero-termin
1d940 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 ated.** string r
1d950 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 epresentation as
1d960 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1d970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
1d980 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 t()]..**.** A re
1d990 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 sult table might
1d9a0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 consist of one
1d9b0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 or more memory a
1d9c0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 llocations..** I
1d9d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
1d9e0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 pass a result t
1d9f0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f able directly to
1da00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1da10 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 ]..** A result t
1da20 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 able should be d
1da30 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 eallocated using
1da40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1da50 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e able()]..**.** ^
1da60 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f (As an example o
1da70 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
1da80 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f le format, suppo
1da90 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c se a query resul
1daa0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f t.** is as follo
1dab0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1dac0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1dad0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 Name
1dae0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 | Age.**
1daf0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d --------------
1db00 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 ---------.**
1db10 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 Alice
1db20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 | 43.** B
1db30 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a ob | 28.
1db40 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 ** Cindy
1db50 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f | 21.** </
1db60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1db70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 >.**.** There ar
1db80 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d e two column (M=
1db90 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f =2) and three ro
1dba0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 ws (N==3). Thus
1dbb0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 the.** result t
1dbc0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 able has 8 entri
1dbd0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 es. Suppose the
1dbe0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
1dbf0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e stored.** in an
1dc00 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 array names azR
1dc10 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 esult. Then azR
1dc20 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 esult holds this
1dc30 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 content:.**.**
1dc40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1dc50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 >.** azRe
1dc60 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e sult[0] = "N
1dc70 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ame";.**
1dc80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 azResult[1]
1dc90 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 = "Age";.**
1dca0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1dcb0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 2] = "Alice";.**
1dcc0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1dcd0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a [3] = "43";.
1dce0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1dcf0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 lt[4] = "Bob
1dd00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1dd10 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 esult[5] = "
1dd20 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 28";.** a
1dd30 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d zResult[6] =
1dd40 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 "Cindy";.**
1dd50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1dd60 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c ;7] = "21";.** <
1dd70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1dd80 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e>)^.**.** ^The
1dd90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1dda0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
1ddb0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
1ddc0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
1ddd0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
1dde0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
1ddf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1de00 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
1de10 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
1de20 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 eter and returns
1de30 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 a result table
1de40 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 to the.** pointe
1de50 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 r given in its 3
1de60 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a rd parameter..**
1de70 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 .** After the ap
1de80 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 plication has fi
1de90 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 nished with the
1dea0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 result from sqli
1deb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c te3_get_table(),
1dec0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 .** it must pass
1ded0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1dee0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c e pointer to sql
1def0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1df00 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a ) in order to.**
1df10 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1df20 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c ory that was mal
1df30 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 loced. Because
1df40 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a of the way the.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
1df60 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 c()] happens wit
1df70 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hin sqlite3_get_
1df80 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c table(), the cal
1df90 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ling.** function
1dfa0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f must not try to
1dfb0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 call [sqlite3_f
1dfc0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e ree()] directly.
1dfd0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 Only.** [sqlit
1dfe0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1dff0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 is able to rele
1e000 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 ase the memory p
1e010 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 roperly and safe
1e020 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ly..**.** The sq
1e030 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1e040 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
1e050 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 mplemented as a
1e060 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a wrapper around.*
1e070 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * [sqlite3_exec(
1e080 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 )]. The sqlite3
1e090 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 _get_table() rou
1e0a0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 tine does not ha
1e0b0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ve access.** to
1e0c0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 any internal dat
1e0d0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 a structures of
1e0e0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 SQLite. It uses
1e0f0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 only the public
1e100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 .** interface de
1e110 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 fined here. As
1e120 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 a consequence, e
1e130 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 rrors that occur
1e140 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 in the.** wrapp
1e150 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 er layer outside
1e160 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c of the internal
1e170 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1e180 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a ] call are not.*
1e190 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 * reflected in s
1e1a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
1e1b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
1e1c0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 ode()] or.** [sq
1e1d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e lite3_errmsg()].
1e1e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1e1f0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
1e200 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 able(. sqlite3
1e210 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a *db, /*
1e220 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
1e230 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1e240 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 r *zSql, /*
1e250 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 SQL to be evalua
1e260 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ted */. char **
1e270 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f *pazResult, /
1e280 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 * Results of the
1e290 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 query */. int
1e2a0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 *pnRow,
1e2b0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1e2c0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
1e2d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
1e2e0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 *pnColumn,
1e2f0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1e300 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 result columns w
1e310 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1e320 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 char **pzErrmsg
1e330 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 /* Error
1e340 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 msg written here
1e350 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
1e360 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 I void sqlite3_f
1e370 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1e380 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1e390 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1e3a0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1e3b0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1e3c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1e3d0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1e3e0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1e3f0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1e400 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1e410 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1e420 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 library..**.**
1e430 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 ^The sqlite3_mpr
1e440 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
1e450 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
1e460 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
1e470 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
1e480 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
1e490 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
1e4a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
1e4b0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1e4c0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
1e4d0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
1e4e0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
1e4f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
1e500 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
1e510 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
1e520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1e530 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1e540 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
1e550 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
1e560 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
1e570 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
1e580 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
1e590 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 (The sqlite3_snp
1e5a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1e5b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
1e5c0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
1e5d0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
1e5e0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
1e5f0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
1e600 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
1e610 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
1e620 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1e630 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
1e640 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
1e650 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1e660 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
1e670 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
1e680 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
1e690 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
1e6a0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
1e6b0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 f().)^ This is
1e6c0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
1e6d0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
1e6e0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
1e6f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
1e700 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
1e710 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e patibility. ^(N
1e720 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 ote also that sq
1e730 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1e740 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f .** returns a po
1e750 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 inter to its buf
1e760 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 fer instead of t
1e770 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1e780 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 characters actua
1e790 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
1e7a0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 the buffer.)^
1e7b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
1e7c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1e7d0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
1e7e0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
1e7f0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
1e800 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
1e810 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
1e820 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1e830 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1e840 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
1e850 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
1e860 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1e870 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 .** ^As long as
1e880 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
1e890 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
1e8a0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
1e8b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
1e8c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
1e8d0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
1e8e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1e8f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a . ^The first.**
1e900 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 parameter "n" i
1e910 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 s the total size
1e920 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 of the buffer,
1e930 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 including space
1e940 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 for.** the zero
1e950 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 terminator. So
1e960 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 the longest stri
1e970 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 ng that can be c
1e980 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 ompletely.** wri
1e990 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 tten will be n-1
1e9a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
1e9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1e9c0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 vsnprintf() rout
1e9d0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 ine is a varargs
1e9e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 version of sqli
1e9f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a te3_snprintf()..
1ea00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1ea10 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
1ea20 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
1ea30 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
1ea40 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
1ea50 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
1ea60 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
1ea70 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
1ea80 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
1ea90 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
1eaa0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
1eab0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
1eac0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
1ead0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
1eae0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1eaf0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1eb00 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1eb10 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1eb20 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
1eb30 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1eb40 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
1eb50 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
1eb60 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
1eb70 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
1eb80 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
1eb90 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
1eba0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
1ebb0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
1ebc0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
1ebd0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
1ebe0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
1ebf0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
1ec00 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
1ec10 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
1ec20 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
1ec30 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
1ec40 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
1ec50 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
1ec60 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
1ec70 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1ec80 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1ec90 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
1eca0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
1ecb0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
1ecc0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1ecd0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
1ece0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
1ecf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1ed00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1ed10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1ed20 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1ed30 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1ed40 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1ed50 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
1ed60 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
1ed70 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1ed80 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1ed90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1eda0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1edb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1edc0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
1edd0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
1ede0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
1edf0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
1ee00 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
1ee10 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
1ee20 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
1ee30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1ee40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1ee50 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1ee60 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1ee70 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
1ee80 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
1ee90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1eea0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
1eeb0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
1eec0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
1eed0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
1eee0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
1eef0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
1ef00 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
1ef10 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1ef20 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
1ef30 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
1ef40 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
1ef50 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1ef60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1ef70 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
1ef80 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
1ef90 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
1efa0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
1efb0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
1efc0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
1efd0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
1efe0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
1eff0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
1f000 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
1f010 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
1f020 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
1f030 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
1f040 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
1f050 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
1f060 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
1f070 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
1f080 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
1f090 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
1f0a0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
1f0b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1f0c0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
1f0d0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
1f0e0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
1f0f0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
1f100 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
1f110 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
1f120 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1f130 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1f140 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1f150 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1f160 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1f170 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
1f180 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1f190 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1f1a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1f1b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1f1c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1f1d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
1f1e0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
1f1f0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
1f200 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
1f210 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
1f220 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
1f230 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
1f240 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1f250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1f260 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
1f270 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1f280 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 "%s" but with th
1f290 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
1f2a0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
1f2b0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
1f2c0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
1f2d0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
1f2e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1f2f0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
1f300 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
1f310 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
1f320 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d char *sqlite3_m
1f330 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1f340 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f r*,...);.SQLITE_
1f350 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
1f360 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 3_vmprintf(const
1f370 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1f380 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
1f390 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 r *sqlite3_snpri
1f3a0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1f3b0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b nst char*, ...);
1f3c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1f3d0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 *sqlite3_vsnpri
1f3e0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1f3f0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1f400 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 st);../*.** CAPI
1f410 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1f420 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
1f430 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
1f440 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
1f450 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
1f460 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
1f470 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
1f480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1f490 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
1f4a0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
1f4b0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
1f4c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
1f4d0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
1f4e0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
1f4f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
1f500 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
1f510 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
1f520 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1f530 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
1f540 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
1f550 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f560 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1f570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1f580 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
1f590 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
1f5a0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
1f5b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
1f5c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
1f5d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f5e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
1f5f0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
1f600 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
1f610 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
1f620 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
1f630 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
1f640 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
1f650 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
1f660 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
1f670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f680 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
1f690 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
1f6a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
1f6b0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
1f6c0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
1f6d0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
1f6e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
1f6f0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1f700 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
1f710 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
1f720 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
1f730 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
1f740 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
1f750 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
1f760 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
1f770 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
1f780 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
1f790 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
1f7a0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
1f7b0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
1f7c0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
1f7d0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
1f7e0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
1f7f0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
1f800 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
1f810 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
1f820 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
1f830 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
1f840 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1f850 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
1f860 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
1f870 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
1f880 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1f890 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
1f8a0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
1f8b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
1f8c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1f8d0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1f8e0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
1f8f0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
1f900 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
1f910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1f920 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
1f930 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 oc()..**.** ^(Th
1f940 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
1f950 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
1f960 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
1f970 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
1f980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
1f990 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
1f9a0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
1f9b0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
1f9c0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
1f9d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1f9e0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
1f9f0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
1fa00 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 arameter.)^ ^ If
1fa10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1fa20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1fa30 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
1fa40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1fa50 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
1fa60 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
1fa70 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1fa80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
1fa90 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1faa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1fab0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1fac0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 ()..** ^If the s
1fad0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1fae0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1faf0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a oc() is zero or.
1fb00 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
1fb10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1fb20 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
1fb30 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
1fb40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 sqlite3_free(P)
1fb50 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 where P is the f
1fb60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1fb70 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1fb80 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 c()..** ^sqlite3
1fb90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
1fba0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1fbb0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
1fbc0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
1fbd0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
1fbe0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
1fbf0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
1fc00 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
1fc10 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 ** ^If M is the
1fc20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
1fc30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
1fc40 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
1fc50 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
1fc60 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
1fc70 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
1fc80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
1fc90 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
1fca0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
1fcb0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
1fcc0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
1fcd0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
1fce0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1fcf0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
1fd00 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
1fd10 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
1fd20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
1fd30 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
1fd40 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1fd50 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
1fd60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
1fd70 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1fd80 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1fd90 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1fda0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1fdb0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1fdc0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1fdd0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1fde0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1fdf0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1fe00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1fe10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1fe20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1fe30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1fe40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1fe50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1fe60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1fe70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1fe80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1fe90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1fea0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1feb0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1fec0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1fed0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1fee0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1fef0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1ff00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1ff10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1ff20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1ff30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1ff40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1ff50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1ff60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1ff70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1ff80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1ff90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1ffa0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1ffb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1ffc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1ffd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1ffe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1fff0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
20000 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
20010 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
20020 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
20030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
20040 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
20050 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
20060 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
20070 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
20080 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
20090 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
200a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
200b0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
200c0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
200d0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
200e0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
200f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
20100 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
20110 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
20120 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
20130 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
20140 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
20150 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
20160 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
20170 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
20180 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
20190 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
201a0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
201b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
201c0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
201d0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
201e0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
201f0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
20200 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
20210 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
20220 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
20230 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c alloc()]..*/.SQL
20240 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
20250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
20260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
20270 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
20280 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b loc(void*, int);
20290 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
202a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
202b0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
202c0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
202d0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 locator Statisti
202e0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 cs.**.** SQLite
202f0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 provides these t
20300 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f wo interfaces fo
20310 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 r reporting on t
20320 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 he status.** of
20330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c the [sqlite3_mal
20340 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 loc()], [sqlite3
20350 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _free()], and [s
20360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
20370 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 ].** routines, w
20380 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 hich form the bu
20390 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c ilt-in memory al
203a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
203b0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b em..**.** ^The [
203c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
203d0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 sed()] routine r
203e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
203f0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 r of bytes.** of
20400 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c memory currentl
20410 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d y outstanding (m
20420 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 alloced but not
20430 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 freed)..** ^The
20440 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
20450 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 highwater()] rou
20460 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
20470 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 maximum.** valu
20480 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 e of [sqlite3_me
20490 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e mory_used()] sin
204a0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 ce the high-wate
204b0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 r mark.** was la
204c0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 st reset. ^The
204d0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
204e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
204f0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a ry_used()] and.*
20500 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
20510 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
20520 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 nclude any overh
20530 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 ead.** added by
20540 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d SQLite in its im
20550 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
20560 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
20570 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f )],.** but not o
20580 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 verhead added by
20590 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 the any underly
205a0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 ing system libra
205b0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 ry.** routines t
205c0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c hat [sqlite3_mal
205d0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e loc()] may call.
205e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
205f0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 ry high-water ma
20600 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 rk is reset to t
20610 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
20620 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f of.** [sqlite3_
20630 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 memory_used()] i
20640 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
20650 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a e parameter to.*
20660 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 * [sqlite3_memor
20670 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 y_highwater()] i
20680 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 s true. ^The va
20690 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
206a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f by [sqlite3_memo
206b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d ry_highwater(1)]
206c0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 is the high-wat
206d0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 er mark.** prior
206e0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a to the reset..*
206f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c /.SQLITE_API sql
20700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
20710 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
20720 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
20730 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
20740 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
20750 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
20760 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
20770 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d API3REF: Pseudo-
20780 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 Random Number Ge
20790 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 nerator.**.** SQ
207a0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 Lite contains a
207b0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
207c0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 udo-random numbe
207d0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e r generator (PRN
207e0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 G) used to.** se
207f0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 lect random [ROW
20800 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 ID | ROWIDs] whe
20810 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 n inserting new
20820 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 records into a t
20830 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 able that.** alr
20840 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 eady uses the la
20850 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b rgest possible [
20860 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e ROWID]. The PRN
20870 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 G is also used f
20880 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d or.** the build-
20890 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 in random() and
208a0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c randomblob() SQL
208b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 functions. Thi
208c0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
208d0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f ws.** applicatio
208e0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 ns to access the
208f0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f same PRNG for o
20900 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a ther purposes..*
20910 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 *.** ^A call to
20920 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
20930 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
20940 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
20950 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e uffer P..**.** ^
20960 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
20970 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 his routine is i
20980 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 nvoked (either i
20990 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a nternally or by.
209a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
209b0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 on) the PRNG is
209c0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
209d0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
209e0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 .** from the xRa
209f0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
20a00 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
20a10 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
20a20 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 ect..** ^On all
20a30 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
20a40 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 ations, the pseu
20a50 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 do-randomness is
20a60 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e generated.** in
20a70 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 ternally and wit
20a80 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f hout recourse to
20a90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
20aa0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a s] xRandomness.*
20ab0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c * method..*/.SQL
20ac0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
20ad0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
20ae0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
20af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
20b00 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
20b10 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
20b20 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
20b30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
20b40 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a ters an authoriz
20b50 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
20b60 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
20b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
20b80 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
20b90 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
20ba0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
20bb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20bc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ack is invoked a
20bd0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 s SQL statements
20be0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 are being compi
20bf0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 led.** by [sqlit
20c00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
20c10 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 its variants [s
20c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20c30 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
20c40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 3_prepare16()] a
20c50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
20c60 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 are16_v2()]. ^A
20c70 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 t various.** poi
20c80 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 nts during the c
20c90 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 ompilation proce
20ca0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 ss, as logic is
20cb0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a being created.**
20cc0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
20cd0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 ous actions, the
20ce0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20cf0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
20d00 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f to.** see if tho
20d10 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 se actions are a
20d20 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 llowed. ^The au
20d30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20d40 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 k should.** retu
20d50 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 rn [SQLITE_OK] t
20d60 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 o allow the acti
20d70 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f on, [SQLITE_IGNO
20d80 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 RE] to disallow
20d90 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
20da0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 action but allow
20db0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
20dc0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 nt to continue t
20dd0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 o be.** compiled
20de0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
20df0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 Y] to cause the
20e00 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 entire SQL state
20e10 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 ment to be.** re
20e20 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 jected with an e
20e30 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 rror. ^If the a
20e40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
20e50 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ck returns.** an
20e60 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
20e70 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 an [SQLITE_IGNOR
20e80 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c E], [SQLITE_OK],
20e90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
20ea0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 ].** then the [s
20eb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
20ec0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
20ed0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
20ee0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 ggered.** the au
20ef0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
20f00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
20f10 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
20f20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
20f30 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
20f40 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e E_OK], that mean
20f50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a s the operation.
20f60 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 ** requested is
20f70 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 ok. ^When the c
20f80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
20f90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 [SQLITE_DENY], t
20fa0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 he.** [sqlite3_p
20fb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
20fc0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
20fd0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
20fe0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
20ff0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
21000 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
21010 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 explaining that
21020 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 .** access is de
21030 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 nied. .**.** ^Th
21040 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
21050 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
21060 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
21070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
21080 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
21090 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
210a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
210b0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 interface. ^The
210c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
210d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c r.** to the call
210e0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
210f0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 er [SQLITE_COPY
21100 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 | action code] t
21110 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
21120 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
21130 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
21140 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 horized. ^The th
21150 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
21160 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 h parameters.**
21170 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
21180 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 are zero-termina
21190 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
211a0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f contain additio
211b0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 nal.** details a
211c0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 bout the action
211d0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
211e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
211f0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
21200 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
21210 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
21220 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
21230 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
21240 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
21250 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
21260 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
21270 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
21280 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
21290 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
212a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
212b0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
212c0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
212d0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
212e0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
212f0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
21300 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
21310 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
21320 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
21330 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
21340 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
21350 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
21360 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
21370 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
21380 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 DELETE] and the
21390 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
213a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f .** [SQLITE_IGNO
213b0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 RE] then the [DE
213c0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 LETE] operation
213d0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 proceeds but the
213e0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 .** [truncate op
213f0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 timization] is d
21400 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 isabled and all
21410 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 rows are deleted
21420 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a individually..*
21430 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a *.** An authoriz
21440 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 er is used when
21450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21460 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a | preparing].**
21470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
21480 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 from an untruste
21490 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 d source, to ens
214a0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ure that the SQL
214b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 statements.** d
214c0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 o not try to acc
214d0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 ess data they ar
214e0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f e not allowed to
214f0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 see, or that th
21500 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 ey do not.** try
21510 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 to execute mali
21520 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 cious statements
21530 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 that damage the
21540 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a database. For.
21550 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 ** example, an a
21560 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 pplication may a
21570 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 llow a user to e
21580 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a nter arbitrary.*
21590 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f * SQL queries fo
215a0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 r evaluation by
215b0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 a database. But
215c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
215d0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
215e0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 t the user to be
215f0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 able to make ar
21600 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 bitrary changes
21610 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 to the.** databa
21620 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a se. An authoriz
21630 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 er could then be
21640 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 put in place wh
21650 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d ile the.** user-
21660 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 entered SQL is b
21670 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 eing [sqlite3_pr
21680 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 epare | prepared
21690 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c ] that.** disall
216a0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 ows everything e
216b0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 xcept [SELECT] s
216c0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
216d0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
216e0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 at need to proce
216f0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 ss SQL from untr
21700 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a usted sources.**
21710 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 might also cons
21720 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 ider lowering re
21730 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 source limits us
21740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
21750 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d it()].** and lim
21760 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 iting database s
21770 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d ize using the [m
21780 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b ax_page_count] [
21790 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 PRAGMA].** in ad
217a0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 dition to using
217b0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a an authorizer..*
217c0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 *.** ^(Only a si
217d0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ngle authorizer
217e0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 can be in place
217f0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f on a database co
21800 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 nnection.** at a
21810 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c time. Each cal
21820 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 l to sqlite3_set
21830 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 _authorizer over
21840 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 rides the.** pre
21850 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e vious call.)^ ^
21860 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 Disable the auth
21870 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c orizer by instal
21880 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c ling a NULL call
21890 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 back..** The aut
218a0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 horizer is disab
218b0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
218c0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
218d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 izer callback mu
218e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
218f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
21900 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
21910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
21920 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
21930 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
21940 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ack..** Note tha
21950 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
21960 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
21970 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
21980 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
21990 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
219a0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
219b0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
219c0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
219d0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 graph..**.** ^Wh
219e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
219f0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
21a00 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
21a10 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
21a20 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
21a30 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 be re-prepared
21a40 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f during [sqlite3_
21a50 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 step()] due to a
21a60 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e .** schema chan
21a70 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 ge. Hence, the
21a80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
21a90 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 ld ensure that t
21aa0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 he.** correct au
21ab0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21ac0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 k remains in pla
21ad0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 ce during the [s
21ae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
21af0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
21b00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
21b20 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
21b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
21b40 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
21b50 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
21b60 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
21b70 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
21b80 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
21b90 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
21ba0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 e3_step()], unle
21bb0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 ss.** as stated
21bc0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
21bd0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 paragraph, sqlit
21be0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 e3_step() invoke
21bf0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 s.** sqlite3_pre
21c00 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 pare_v2() to rep
21c10 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 repare a stateme
21c20 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d nt after a schem
21c30 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c a change..*/.SQL
21c40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
21c50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
21c60 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a er(. sqlite3*,.
21c70 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 int (*xAuth)(v
21c80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
21c90 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
21ca0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
21cb0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 st char*),. voi
21cc0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a d *pUserData.);.
21cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
21ce0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 Authorizer Retu
21cf0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 rn Codes.**.** T
21d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
21d10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
21d20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21d30 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
21d40 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
21d50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
21d60 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
21d70 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
21d80 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
21d90 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
21da0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
21db0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
21dc0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
21dd0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21de0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
21df0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
21e00 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
21e10 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
21e20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
21e30 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 QLITE_IGNORE is
21e40 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b also used as a [
21e50 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 SQLITE_ROLLBACK
21e60 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a | return code].*
21e70 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 * from the [sqli
21e80 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 te3_vtab_on_conf
21e90 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 lict()] interfac
21ea0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
21eb0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
21ec0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
21ed0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
21ee0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
21ef0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
21f00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
21f10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
21f20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
21f30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
21f40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
21f50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
21f60 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
21f70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
21f80 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
21f90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
21fa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
21fb0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
21fc0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
21fd0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
21fe0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
21ff0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
22000 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
22010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
22020 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
22030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
22040 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
22050 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
22060 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
22070 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
22080 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
22090 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
220a0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
220b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
220c0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
220d0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
220e0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
220f0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
22100 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
22110 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
22120 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
22130 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
22140 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
22150 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
22160 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
22170 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
22180 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
22190 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
221a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
221b0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d ^(The 5th param
221c0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
221d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
221e0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
221f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
22200 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
22210 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
22220 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 icable.)^ ^The
22230 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
22240 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
22250 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
22260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
22270 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
22280 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
22290 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
222a0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
222b0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
222c0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
222d0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
222e0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
222f0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
22300 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
22310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 ************** 3
22330 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 rd ************
22340 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 4th ***********/
22350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22360 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 CREATE_INDEX
22370 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 1 /* Ind
22380 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
22390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
223a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
223b0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 REATE_TABLE
223c0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 2 /* Tabl
223d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
223e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
223f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
22400 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 EATE_TEMP_INDEX
22410 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 3 /* Index
22420 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
22430 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
22440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
22450 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ATE_TEMP_TABLE
22460 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4 /* Table
22470 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
22480 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
22490 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
224a0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 TE_TEMP_TRIGGER
224b0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 5 /* Trigger
224c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
224d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
224e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
224f0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 E_TEMP_VIEW
22500 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 6 /* View Nam
22510 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
22520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22540 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
22550 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 7 /* Trigger N
22560 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
22570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
22580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22590 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 VIEW 8
225a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
225b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
225c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
225d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 SQLITE_DELETE
225e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 9
225f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22620 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 SQLITE_DROP_INDE
22630 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 X 10
22640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
22650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
22660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22670 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 QLITE_DROP_TABLE
22680 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 11
22690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
226a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
226b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
226c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 LITE_DROP_TEMP_I
226d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f NDEX 12 /
226e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
226f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
22700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22710 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 ITE_DROP_TEMP_TA
22720 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a BLE 13 /*
22730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22760 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 TE_DROP_TEMP_TRI
22770 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 GGER 14 /*
22780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
22790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
227a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
227b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 E_DROP_TEMP_VIEW
227c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 15 /* V
227d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
227e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
227f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22800 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 _DROP_TRIGGER
22810 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 16 /* Tr
22820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
22830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22850 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 DROP_VIEW
22860 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 17 /* Vie
22870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
22880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
228a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 NSERT
228b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 18 /* Tabl
228c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
228d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
228f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
22900 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 19 /* Pragm
22910 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 a Name 1st a
22920 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 rg or NULL */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
22940 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
22950 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 20 /* Table
22960 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
22970 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 fine SQLITE_SELE
22990 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CT
229a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 21 /* NULL
229b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 NULL
229c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
229e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 ACTION
229f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 22 /* Operatio
22a00 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 n NULL
22a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 ne SQLITE_UPDATE
22a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
22a40 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
22a50 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
22a60 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 e SQLITE_ATTACH
22a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 24
22a90 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 /* Filename
22aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22ac0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 SQLITE_DETACH
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 25
22ae0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
22af0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 me NULL
22b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22b10 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 SQLITE_ALTER_TAB
22b20 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 LE 26
22b30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
22b40 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 e Table Name
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22b60 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 QLITE_REINDEX
22b70 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 27
22b80 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
22b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22bb0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 LITE_ANALYZE
22bc0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 28 /
22bd0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22c00 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c ITE_CREATE_VTABL
22c10 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a E 29 /*
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22c30 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22c50 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 TE_DROP_VTABLE
22c60 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 30 /*
22c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22c80 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22ca0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 E_FUNCTION
22cb0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 31 /* N
22cc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 ULL F
22cd0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a unction Name *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22cf0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 _SAVEPOINT
22d00 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 32 /* Op
22d10 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 eration Sa
22d20 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f vepoint Name */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22d40 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 COPY
22d50 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 0 /* No
22d60 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a longer used */..
22d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22d80 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
22d90 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
22da0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
22db0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 ines register ca
22dc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 llback functions
22dd0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 that can be use
22de0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 d for.** tracing
22df0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 and profiling t
22e00 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
22e10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
22e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
22e30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
22e40 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
22e50 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e e3_trace() is in
22e60 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 voked at.** vari
22e70 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 ous times when a
22e80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
22e90 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 is being run by
22ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
22eb0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
22ec0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
22ed0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
22ee0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 th a UTF-8 rende
22ef0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 ring of the.** S
22f00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
22f10 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 t as the stateme
22f20 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
22f30 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 executing..** ^(
22f40 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 Additional sqlit
22f50 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
22f60 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 acks might occur
22f70 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
22f80 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
22f90 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
22fa0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
22fb0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
22fc0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
22fd0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
22fe0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
22ff0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ger.)^.**.** ^Th
23000 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
23010 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
23020 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c y sqlite3_profil
23030 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
23040 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 * as each SQL st
23050 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 atement finishes
23060 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
23070 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
23080 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 s.** the origina
23090 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 l statement text
230a0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 and an estimate
230b0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 of wall-clock t
230c0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f ime.** of how lo
230d0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e ng that statemen
230e0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 t took to run.
230f0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
23100 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 lback.** time is
23110 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e in units of nan
23120 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 oseconds, howeve
23130 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d r the current im
23140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
23150 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 is only capable
23160 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 of millisecond r
23170 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 esolution so the
23180 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 six least signi
23190 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 ficant.** digits
231a0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 in the time are
231b0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 meaningless. F
231c0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
231d0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 f SQLite.** migh
231e0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 t provide greate
231f0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 r resolution on
23200 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c the profiler cal
23210 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 lback. The.** s
23220 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
23230 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e function is con
23240 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 sidered experime
23250 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 ntal and is.** s
23260 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
23270 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
23280 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
23290 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
232a0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
232b0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
232c0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
232d0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
232e0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 d*);.SQLITE_API
232f0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
23300 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
23310 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
23320 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
23330 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
23340 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
23350 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
23360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
23370 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
23380 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a s Callbacks.**.*
23390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 * ^The sqlite3_p
233a0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
233b0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 D,N,X,P) interfa
233c0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 ce causes the ca
233d0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
233e0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b on X to be invok
233f0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
23400 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e during long runn
23410 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ing calls to.**
23420 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
23430 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
23440 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
23450 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 get_table()] for
23460 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
23470 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 nection D. An e
23480 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
23490 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
234a0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
234b0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
234c0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
234d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d **.** ^The param
234e0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 eter P is passed
234f0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
23500 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
23510 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 o the .** callba
23520 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 ck function X.
23530 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e ^The parameter N
23540 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
23550 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d f .** [virtual m
23560 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 achine instructi
23570 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 ons] that are ev
23580 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 aluated between
23590 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e successive.** in
235a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
235b0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a callback X..**.
235c0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c ** ^Only a singl
235d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
235e0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 er may be define
235f0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 d at one time pe
23600 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
23610 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 onnection]; sett
23620 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 ing a new progre
23630 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 ss handler cance
23640 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e ls the.** old on
23650 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 e. ^Setting par
23660 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c ameter X to NULL
23670 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 disables the pr
23680 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
23690 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 ** ^The progress
236a0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f handler is also
236b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 disabled by set
236c0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 ting N to a valu
236d0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 e less.** than 1
236e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
236f0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
23700 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
23710 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f ro, the operatio
23720 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 n is.** interrup
23730 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 ted. This featu
23740 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 re can be used t
23750 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a o implement a.**
23760 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e "Cancel" button
23770 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 on a GUI progre
23780 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a ss dialog box..*
23790 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 *.** The progres
237a0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 s handler callba
237b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
237c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
237d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
237e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
237f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
23800 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
23810 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 ndler..** Note t
23820 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
23830 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
23840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
23850 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
23860 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
23870 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
23880 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
23890 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
238a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 ragraph..**.*/.S
238b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
238c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
238d0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
238e0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
238f0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
23900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
23910 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
23920 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
23930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
23940 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 utines open an S
23950 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 QLite database f
23960 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 ile as specified
23970 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 by the .** file
23980 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e name argument. ^
23990 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
239a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
239b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
239c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
239d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
239e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
239f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
23a00 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
23a10 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
23a20 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 open16(). ^(A [d
23a30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23a40 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 on] handle is us
23a50 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ually.** returne
23a60 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e d in *ppDb, even
23a70 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
23a80 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 urs. The only e
23a90 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 xception is that
23aa0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 .** if SQLite is
23ab0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
23ac0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
23ad0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ld the [sqlite3]
23ae0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 object,.** a NU
23af0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 LL will be writt
23b00 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e en into *ppDb in
23b10 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 stead of a point
23b20 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
23b30 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e e3].** object.)^
23b40 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 ^(If the databa
23b50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
23b60 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
23b70 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
23b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
23b90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
23ba0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
23bb0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
23bc0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b ned.)^ ^The.** [
23bd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
23be0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
23bf0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
23c00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
23c10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
23c20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
23c30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
23c40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 he error followi
23c50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 ng a failure of
23c60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 any.** of the sq
23c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 lite3_open() rou
23c80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tines..**.** ^Th
23c90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
23ca0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
23cb0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
23cc0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
23cd0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
23ce0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
23cf0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
23d00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
23d10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
23d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
23d30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
23d40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
23d50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
23d60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
23d70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
23d80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
23d90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
23da0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
23db0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
23dc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
23dd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
23de0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
23df0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
23e00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
23e10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
23e20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
23e30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
23e40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
23e50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
23e60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
23e70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
23e80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
23e90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
23ea0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
23eb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
23ec0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
23ed0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
23ee0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
23ef0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
23f00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
23f10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
23f20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
23f30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
23f40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
23f50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
23f60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
23f70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
23f80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
23f90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c N_PRIVATECACHE],
23fa0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
23fb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a OPEN_URI] flags:
23fc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a )^.**.** <dl>.**
23fd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
23fe0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
23ff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
24000 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
24010 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
24020 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
24030 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
24040 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
24050 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
24060 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
24070 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
24080 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
24090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
240a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
240b0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
240c0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
240d0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
240e0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
240f0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
24100 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
24110 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
24120 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
24130 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
24140 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
24150 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
24160 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
24170 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
24180 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
24190 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
241a0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
241b0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
241c0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
241d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
241e0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
241f0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
24200 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f ated if.** it do
24210 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
24220 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
24230 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
24240 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
24250 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
24260 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
24270 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
24280 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
24290 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
242a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
242b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
242c0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
242d0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
242e0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 wn above optiona
242f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
24300 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 h other.** [SQLI
24310 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
24320 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a | SQLITE_OPEN_*
24330 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 bits].** then t
24340 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
24350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
24360 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
24370 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
24380 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
24390 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
243a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
243b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
243c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
243d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
243e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
243f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
24400 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
24410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
24420 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
24430 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
24440 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
24450 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
24460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
24470 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
24480 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
24490 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
244a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
244b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
244c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
244d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
244e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
244f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
24500 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
24510 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
24520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
24530 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
24540 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
24550 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
24560 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
24570 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
24580 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
24590 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
245a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
245b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
245c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
245d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
245e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
245f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
24600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
24610 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
24620 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
24630 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
24640 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
24650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
24660 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
24670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24680 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
24690 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
246a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
246b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
246c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
246d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
246e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
246f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
24700 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
24710 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
24720 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
24730 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
24740 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
24750 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
24760 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
24770 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
24780 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
24790 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
247a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
247b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
247c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
247d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
247e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
247f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
24800 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
24810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24820 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
24830 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
24840 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
24850 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
24860 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
24870 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
24880 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
24890 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
248a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
248b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
248c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
248d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
248e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
248f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
24900 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
24910 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
24920 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
24930 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
24940 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
24950 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
24960 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
24970 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
24980 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
24990 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
249a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
249b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
249c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
249d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
249e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
249f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
24a00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
24a10 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
24a20 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
24a30 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 enames in sqlite
24a40 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 3_open()]] <h3>U
24a50 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 RI Filenames</h3
24a60 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 >.**.** ^If [URI
24a70 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 filename] inter
24a80 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
24a90 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 bled, and the fi
24aa0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
24ab0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 ** begins with "
24ac0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 file:", then the
24ad0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 filename is int
24ae0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 erpreted as a UR
24af0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e I. ^URI.** filen
24b00 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
24b10 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 on is enabled if
24b20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
24b30 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a N_URI] flag is.*
24b40 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 * set in the fou
24b50 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
24b60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24b70 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
24b80 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
24b90 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
24ba0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
24bb0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
24bc0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
24bd0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
24be0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 hod or by the [S
24bf0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 QLITE_USE_URI] c
24c00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
24c10 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c on..** As of SQL
24c20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
24c30 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 7, URI filename
24c40 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
24c50 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 s turned off.**
24c60 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 by default, but
24c70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
24c80 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
24c90 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e enable URI filen
24ca0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ame.** interpret
24cb0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
24cc0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c . See "[URI fil
24cd0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 enames]" for add
24ce0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
24cf0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 mation..**.** UR
24d00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 I filenames are
24d10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 parsed according
24d20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 to RFC 3986. ^I
24d30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 f the URI contai
24d40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 ns an.** authori
24d50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 ty, then it must
24d60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d be either an em
24d70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 pty string or th
24d80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f e string .** "lo
24d90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 calhost". ^If th
24da0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e e authority is n
24db0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 ot an empty stri
24dc0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 ng or "localhost
24dd0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 ", an .** error
24de0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
24df0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 he caller. ^The
24e00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 fragment compone
24e10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 nt of a URI, if
24e20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 .** present, is
24e30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
24e40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
24e50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f path component o
24e60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 f the URI as the
24e70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 name of the dis
24e80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 k file.** which
24e90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 contains the dat
24ea0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 abase. ^If the p
24eb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 ath begins with
24ec0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c a '/' character,
24ed0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 .** then it is
24ee0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
24ef0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e n absolute path.
24f00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f ^If the path do
24f10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a es not begin .**
24f20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 with a '/' (mea
24f30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 ning that the au
24f40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 thority section
24f50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
24f60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e the URI).** then
24f70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 the path is int
24f80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 erpreted as a re
24f90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a lative path. .**
24fa0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 ^On windows, th
24fb0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e e first componen
24fc0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 t of an absolute
24fd0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 path .** is a d
24fe0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 rive specificati
24ff0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a on (e.g. "C:")..
25000 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 **.** [[core URI
25010 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
25020 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 s]].** The query
25030 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
25040 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 URI may contain
25050 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
25060 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a are interpreted.
25070 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c ** either by SQL
25080 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 ite itself, or b
25090 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f y a [VFS | custo
250a0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 m VFS implementa
250b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 tion]..** SQLite
250c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
250d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
250e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
250f0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
25100 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 <li> <b>vfs</b
25110 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 >: ^The "vfs" pa
25120 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 rameter may be u
25130 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 sed to specify t
25140 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 he name of.**
25150 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 a VFS object t
25160 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 hat provides the
25170 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
25180 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
25190 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 should.** b
251a0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 e used to access
251b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
251c0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 le on disk. ^If
251d0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 this option is s
251e0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 et to.** an
251f0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 empty string the
25200 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a default VFS obj
25210 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 ect is used. ^Sp
25220 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
25230 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 own.** VFS i
25240 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 s an error. ^If
25250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25260 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
25270 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a e vfs option is.
25280 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 ** present,
25290 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 then the VFS spe
252a0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 cified by the op
252b0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 tion takes prece
252c0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 dence over.**
252d0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 the value pass
252e0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 ed as the fourth
252f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
25300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25310 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
25320 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 >mode</b>: ^(The
25330 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
25340 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
25350 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c ther "ro", "rw",
25360 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f .** "rwc", o
25370 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 r "memory". Atte
25380 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
25390 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
253a0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e lue is.** an
253b0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 error)^. .**
253c0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 ^If "ro" is sp
253d0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 ecified, then th
253e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
253f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e ened for read-on
25400 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 ly .** acces
25410 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 s, just as if th
25420 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
25430 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 EADONLY] flag ha
25440 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 d been set in th
25450 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 e .** third
25460 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
25470 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
25480 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 If the mode opti
25490 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a on is set to .**
254a0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 "rw", then
254b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
254c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
254d0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 write (but not c
254e0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 reate) .** a
254f0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c ccess, as if SQL
25500 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
25510 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 TE (but not SQLI
25520 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 TE_OPEN_CREATE)
25530 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e had .** been
25540 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 set. ^Value "rw
25550 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 c" is equivalent
25560 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 to setting both
25570 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f .** SQLITE_
25580 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 OPEN_READWRITE a
25590 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 nd SQLITE_OPEN_C
255a0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 REATE. ^If the
255b0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a mode option is.*
255c0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 * set to "me
255d0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 mory" then a pur
255e0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 e [in-memory dat
255f0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 abase] that neve
25600 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f r reads.** o
25610 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 r writes from di
25620 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 sk is used. ^It
25630 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 is an error to s
25640 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 pecify a value f
25650 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f or.** the mo
25660 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 de parameter tha
25670 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 t is less restri
25680 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 ctive than that
25690 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
256a0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 the flags pa
256b0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 ssed in the thir
256c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
256d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
256e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
256f0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 b>cache</b>: ^Th
25700 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
25710 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
25720 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 either "shared"
25730 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 or.** "priva
25740 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 te". ^Setting it
25750 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 to "shared" is
25760 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
25770 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 tting the.**
25780 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
25790 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 REDCACHE bit in
257a0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
257b0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 nt passed to.**
257c0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e sqlite3_open
257d0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 _v2(). ^Setting
257e0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 the cache parame
257f0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 ter to "private"
25800 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 is .** equi
25810 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
25820 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 g the SQLITE_OPE
25830 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 N_PRIVATECACHE b
25840 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 it..** ^If s
25850 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25860 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
25870 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 "cache" paramet
25880 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e er is present in
25890 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 .** a URI fi
258a0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 lename, its valu
258b0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 e overrides any
258c0 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 behaviour reques
258d0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a ted by setting.*
258e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
258f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f N_PRIVATECACHE o
25900 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 r SQLITE_OPEN_SH
25910 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a AREDCACHE flag..
25920 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
25930 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e Specifying an un
25940 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 known parameter
25950 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d in the query com
25960 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 ponent of a URI
25970 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 is not an.** err
25980 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 or. Future vers
25990 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
259a0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 ight understand
259b0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 additional query
259c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
259d0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 See "[query par
259e0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 ameters with spe
259f0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 cial meaning to
25a00 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 SQLite]" for.**
25a10 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
25a20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b mation..**.** [[
25a30 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 URI filename exa
25a40 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 mples]] <h3>URI
25a50 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 filename example
25a60 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 s</h3>.**.** <ta
25a70 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 ble border="1" a
25a80 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c lign=center cell
25a90 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 padding=5>.** <t
25aa0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e r><th> URI filen
25ab0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 ames <th> Result
25ac0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 s.** <tr><td> fi
25ad0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 le:data.db <td>
25ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
25af0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 n the file "data
25b00 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 .db" in the curr
25b10 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a ent directory..*
25b20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
25b30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
25b40 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 db<br>.**
25b50 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f file:///home/
25b60 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 fred/data.db <br
25b70 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 > .** f
25b80 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f ile://localhost/
25b90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
25ba0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 b <br> <td> .**
25bb0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 Open th
25bc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
25bd0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 "/home/fred/data
25be0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 .db"..** <tr><td
25bf0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 > file://darksta
25c00 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 r/home/fred/data
25c10 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 .db <td> .**
25c20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
25c30 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f "darkstar" is no
25c40 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 t a recognized a
25c50 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 uthority..** <tr
25c60 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 ><td style="whit
25c70 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e e-space:nowrap">
25c80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
25c90 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e le:///C:/Documen
25ca0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 ts%20and%20Setti
25cb0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 ngs/fred/Desktop
25cc0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 /data.db.**
25cd0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c <td> Windows onl
25ce0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 y: Open the file
25cf0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 "data.db" on fr
25d00 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 ed's desktop on
25d10 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 drive.**
25d20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 C:. Note that
25d30 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 the %20 escaping
25d40 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 in this example
25d50 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 is not strictly
25d60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 .** ne
25d70 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 cessary - space
25d80 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 characters can b
25d90 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 e used literally
25da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
25db0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a URI filenames..*
25dc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
25dd0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 data.db?mode=ro&
25de0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 cache=private <t
25df0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
25e00 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e Open file "data.
25e10 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
25e20 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 nt directory for
25e30 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 read-only acces
25e40 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 s..** R
25e50 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
25e60 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 ther or not shar
25e70 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 ed-cache mode is
25e80 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 enabled by.**
25e90 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c default,
25ea0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 use a private c
25eb0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ache..** <tr><td
25ec0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 > file:/home/fre
25ed0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e d/data.db?vfs=un
25ee0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a ix-nolock <td>.*
25ef0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
25f00 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
25f10 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 /data.db". Use t
25f20 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 he special VFS "
25f30 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a unix-nolock"..**
25f40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
25f50 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 ata.db?mode=read
25f60 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 only <td> .**
25f70 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
25f80 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e "readonly" is n
25f90 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f ot a valid optio
25fa0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 n for the "mode"
25fb0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c parameter..** <
25fc0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 /table>.**.** ^U
25fd0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 RI hexadecimal e
25fe0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
25ff0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 (%HH) are suppor
26000 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 ted within the p
26010 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 ath and.** query
26020 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
26030 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 URI. A hexadeci
26040 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
26050 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 nce consists of
26060 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 a.** percent sig
26070 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 n - "%" - follow
26080 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 ed by exactly tw
26090 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 o hexadecimal di
260a0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 gits .** specify
260b0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c ing an octet val
260c0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 ue. ^Before the
260d0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f path or query co
260e0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a mponents of a.**
260f0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 URI filename ar
26100 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 e interpreted, t
26110 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 hey are encoded
26120 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 using UTF-8 and
26130 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 all .** hexadeci
26140 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
26150 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 nces replaced by
26160 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 a single byte c
26170 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a ontaining the.**
26180 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f corresponding o
26190 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 ctet. If this pr
261a0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 ocess generates
261b0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 an invalid UTF-8
261c0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 encoding,.** th
261d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
261e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
261f0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
26200 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 s users:</b> Th
26210 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 e encoding used
26220 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 for the filename
26230 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 argument.** of
26240 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
26250 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
26260 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 v2() must be UTF
26270 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 -8, not whatever
26280 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 .** codepage is
26290 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
262a0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f d. Filenames co
262b0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 ntaining interna
262c0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 tional.** charac
262d0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e ters must be con
262e0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 verted to UTF-8
262f0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 prior to passing
26300 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 them into.** sq
26310 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
26320 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
26330 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 )..**.** <b>Note
26340 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 to Windows Runt
26350 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ime users:</b>
26360 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 The temporary di
26370 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 rectory must be
26380 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 set.** prior to
26390 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
263a0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
263b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 3_open_v2(). Ot
263c0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 herwise, various
263d0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 .** features tha
263e0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 t require the us
263f0 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 e of temporary f
26400 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a iles may fail..*
26410 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
26420 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
26430 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 ectory].*/.SQLIT
26440 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
26450 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 3_open(. const
26460 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 char *filename,
26470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 /* Database fi
26480 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a lename (UTF-8) *
26490 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
264a0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
264b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
264c0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 ndle */.);.SQLIT
264d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
264e0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 3_open16(. cons
264f0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 t void *filename
26500 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
26510 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 filename (UTF-16
26520 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
26530 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
26540 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
26550 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 handle */.);.SQ
26560 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
26570 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
26580 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
26590 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
265a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
265b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
265c0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
265d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
265e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
265f0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
26600 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
26610 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
26620 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
26630 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
26640 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
26650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26660 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 : Obtain Values
26670 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 For URI Paramete
26680 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 rs.**.** These a
26690 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 re utility routi
266a0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 nes, useful to V
266b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
266c0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a ns, that check.*
266d0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 * to see if a da
266e0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 tabase file was
266f0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 a URI that conta
26700 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 ined a specific
26710 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 query .** parame
26720 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f ter, and if so o
26730 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 btains the value
26740 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 of that query p
26750 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
26760 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 If F is the data
26770 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f base filename po
26780 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 inter passed int
26790 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 o the xOpen() me
267a0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 thod of .** a VF
267b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
267c0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 when the flags
267d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
267e0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 en() has one or
267f0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 .** more of the
26800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
26810 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ] or [SQLITE_OPE
26820 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 N_MAIN_DB] bits
26830 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 set and.** P is
26840 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
26850 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c query parameter,
26860 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
26870 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
26880 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 ,P) returns the
26890 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a value of the P.*
268a0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 * parameter if i
268b0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 t exists or a NU
268c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 LL pointer if P
268d0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 does not appear
268e0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 as a .** query p
268f0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 arameter on F.
26900 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 If P is a query
26910 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a parameter of F.*
26920 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 * has no explici
26930 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 t value, then sq
26940 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
26950 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
26960 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
26970 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
26980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
26990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
269a0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 F,P,B) routine a
269b0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 ssumes that P is
269c0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 a boolean.** pa
269d0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 rameter and retu
269e0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 rns true (1) or
269f0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 false (0) accord
26a00 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ing to the value
26a10 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 .** of P. The s
26a20 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
26a30 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
26a40 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
26a50 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 1) if the.** val
26a60 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 ue of query para
26a70 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f meter P is one o
26a80 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c f "yes", "true",
26a90 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a or "on" in any.
26aa0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 ** case or if th
26ab0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
26ac0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e ith a non-zero n
26ad0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 umber. The .**
26ae0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
26af0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
26b00 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 nes returns fals
26b10 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c e (0) if the val
26b20 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 ue of.** query p
26b30 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e arameter P is on
26b40 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 e of "no", "fals
26b50 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 e", or "off" in
26b60 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 any case or.** i
26b70 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 f the value begi
26b80 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 ns with a numeri
26b90 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 c zero. If P is
26ba0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 not a query.**
26bb0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f parameter on F o
26bc0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f r if the value o
26bd0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 f P is does not
26be0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 match any of the
26bf0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 .** above, then
26c00 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
26c10 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
26c20 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a ns (B!=0)..**.**
26c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
26c40 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f _int64(F,P,D) ro
26c50 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 utine converts t
26c60 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e he value of P in
26c70 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 to a.** 64-bit s
26c80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
26c90 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 d returns that i
26ca0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 nteger, or D if
26cb0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 P does not.** ex
26cc0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c ist. If the val
26cd0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 ue of P is somet
26ce0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
26cf0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e an integer, then
26d00 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 .** zero is retu
26d10 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 rned..** .** If
26d20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e F is a NULL poin
26d30 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ter, then sqlite
26d40 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
26d50 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c F,P) returns NUL
26d60 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 L and.** sqlite3
26d70 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
26d80 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 ,B) returns B.
26d90 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 If F is not a NU
26da0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a LL pointer and.*
26db0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 * is not a datab
26dc0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d ase file pathnam
26dd0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 e pointer that S
26de0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 QLite passed int
26df0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 o the xOpen.** V
26e00 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 FS method, then
26e10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
26e20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
26e30 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
26e40 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 obably.** undesi
26e50 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 rable..*/.SQLITE
26e60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
26e70 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 *sqlite3_uri_par
26e80 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 ameter(const cha
26e90 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f r *zFilename, co
26ea0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
26eb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
26ec0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f t sqlite3_uri_bo
26ed0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 olean(const char
26ee0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 *zFile, const c
26ef0 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 har *zParam, int
26f00 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 bDefault);.SQLI
26f10 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
26f20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 nt64 sqlite3_uri
26f30 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 _int64(const cha
26f40 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c r*, const char*,
26f50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
26f60 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
26f70 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 F: Error Codes A
26f80 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a nd Messages.**.*
26f90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
26fa0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
26fb0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
26fc0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
26fd0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
26fe0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
26ff0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
27000 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
27010 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
27020 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
27030 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
27040 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
27050 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
27060 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
27070 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
27080 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
27090 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
270a0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
270b0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
270c0 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 undefined. ^The
270d0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
270e0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 d_errcode().** i
270f0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 nterface is the
27100 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 same except that
27110 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
27120 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 ns the .** [exte
27130 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
27140 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 ] even when exte
27150 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
27160 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 s are.** disable
27170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
27180 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 lite3_errmsg() a
27190 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 nd sqlite3_errms
271a0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 g16() return Eng
271b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a lish-language.**
271c0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 text that descr
271d0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 ibes the error,
271e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
271f0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 or UTF-16 respec
27200 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d tively..** ^(Mem
27210 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
27220 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
27230 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 ring is managed
27240 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 internally..** T
27250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
27260 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
27270 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 worry about free
27280 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a ing the result..
27290 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
272a0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 error string mig
272b0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ht be overwritte
272c0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 n or deallocated
272d0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e by.** subsequen
272e0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 t calls to other
272f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
27300 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a e functions.)^.*
27310 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
27320 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 3_errstr() inter
27330 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
27340 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 English-languag
27350 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 e text.** that d
27360 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 escribes the [re
27370 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 sult code], as U
27380 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 TF-8..** ^(Memor
27390 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 y to hold the er
273a0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
273b0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e ng is managed in
273c0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 ternally.** and
273d0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 must not be free
273e0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
273f0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 tion)^..**.** Wh
27400 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 en the serialize
27410 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
27420 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 e] is in use, it
27430 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a might be the.**
27440 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 case that a sec
27450 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ond error occurs
27460 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 on a separate t
27470 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e hread in between
27480 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 .** the time of
27490 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 the first error
274a0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 and the call to
274b0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
274c0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 ..** When that h
274d0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f appens, the seco
274e0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 nd error will be
274f0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 reported since
27500 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 these.** interfa
27510 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 ces always repor
27520 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e t the most recen
27530 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 t result. To av
27540 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 oid.** this, eac
27550 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 h thread can obt
27560 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 ain exclusive us
27570 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 e of the [databa
27580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
27590 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 .** by invoking
275a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 [sqlite3_mutex_e
275b0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 nter]([sqlite3_d
275c0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 b_mutex](D)) bef
275d0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a ore beginning.**
275e0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e to use D and in
275f0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f voking [sqlite3_
27600 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 mutex_leave]([sq
27610 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 lite3_db_mutex](
27620 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c D)) after.** all
27630 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e calls to the in
27640 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 terfaces listed
27650 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 here are complet
27660 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 ed..**.** If an
27670 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 interface fails
27680 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 with SQLITE_MISU
27690 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 SE, that means t
276a0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 he interface.**
276b0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f was invoked inco
276c0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 rrectly by the a
276d0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 pplication. In
276e0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a that case, the.*
276f0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 * error code and
27700 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 message may or
27710 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a may not be set..
27720 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
27730 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 t sqlite3_errcod
27740 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a e(sqlite3 *db);.
27750 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
27760 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
27770 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
27780 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
27790 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
277a0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
277b0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 te3*);.SQLITE_AP
277c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
277d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 lite3_errmsg16(s
277e0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
277f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
27800 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 *sqlite3_errstr(
27810 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
27820 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 I3REF: SQL State
27830 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b ment Object.** K
27840 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
27850 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
27860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27870 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
27880 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
27890 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
278a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
278b0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 tement..** This
278c0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 object is variou
278d0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 sly known as a "
278e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
278f0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d nt" or a.** "com
27900 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
27910 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 ent" or simply a
27920 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e s a "statement".
27930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 .**.** The life
27940 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f of a statement o
27950 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 bject goes somet
27960 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a hing like this:.
27970 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
27980 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 i> Create the ob
27990 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
279a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
279b0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a ] or a related.*
279c0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e * function.
279d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
279e0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 lues to [host pa
279f0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 rameters] using
27a00 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
27a10 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 _*().** int
27a20 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e erfaces..** <li>
27a30 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 Run the SQL by
27a40 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
27a50 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 _step()] one or
27a60 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c more times..** <
27a70 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 li> Reset the st
27a80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
27a90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
27aa0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 then go back.**
27ab0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 to step 2.
27ac0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 Do this zero or
27ad0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
27ae0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 <li> Destroy the
27af0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 object using [s
27b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
27b10 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a )]..** </ol>.**.
27b20 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 ** Refer to docu
27b30 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 mentation on ind
27b40 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 ividual methods
27b50 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 above for additi
27b60 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
27b70 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
27b80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
27b90 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
27ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
27bb0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
27bc0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 ts.**.** ^(This
27bd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
27be0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
27bf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
27c00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
27c10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
27c20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
27c30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
27c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
27c50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
27c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
27c70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
27c80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
27c90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
27ca0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
27cb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
27cc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
27cd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
27ce0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
27cf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
27d00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
27d10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
27d20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
27d30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
27d40 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
27d50 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
27d60 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
27d70 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
27d80 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
27d90 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
27da0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
27db0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
27dc0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
27dd0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
27de0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
27df0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
27e00 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
27e10 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
27e20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
27e30 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
27e40 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
27e50 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
27e60 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
27e70 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
27e80 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
27e90 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
27ea0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
27eb0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
27ec0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
27ed0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
27ee0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
27ef0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
27f00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
27f10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
27f20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
27f30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
27f40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
27f50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
27f60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
27f70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
27f80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
27f90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
27fa0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
27fb0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
27fc0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
27fd0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
27fe0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
27ff0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
28000 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
28010 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
28020 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
28030 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
28040 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
28050 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
28060 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
28070 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
28080 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
28090 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
280a0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
280b0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
280c0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
280d0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
280e0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
280f0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
28100 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
28110 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
28120 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
28130 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
28140 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
28150 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
28160 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
28170 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
28180 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
28190 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
281a0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
281b0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
281c0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
281d0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
281e0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
281f0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
28200 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
28210 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
28220 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
28230 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
28240 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
28250 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
28260 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
28270 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
28280 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
28290 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
282a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
282b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
282c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
282d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
282e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
282f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
28300 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
28310 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
28320 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
28330 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
28340 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
28350 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
28360 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
28370 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c qlite3_limit(sql
28380 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 ite3*, int id, i
28390 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a nt newVal);../*.
283a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
283b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 -Time Limit Cate
283c0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 gories.** KEYWOR
283d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 DS: {limit categ
283e0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 ory} {*limit cat
283f0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 egories}.**.** T
28400 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
28410 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 efine various pe
28420 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 rformance limits
28430 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
28440 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 lowered at run-t
28450 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ime using [sqlit
28460 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 e3_limit()]..**
28470 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 The synopsis of
28480 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 the meanings of
28490 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 the various limi
284a0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f ts is shown belo
284b0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c w..** Additional
284c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
284d0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 available at [li
284e0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e mits | Limits in
284f0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 SQLite]..**.**
28500 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
28510 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 _LIMIT_LENGTH]]
28520 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
28530 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a IT_LENGTH</dt>.*
28540 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
28550 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 m size of any st
28560 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 ring or BLOB or
28570 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 table row, in by
28580 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a tes.<dd>)^.**.**
28590 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
285a0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c SQL_LENGTH]] ^(<
285b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
285c0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a SQL_LENGTH</dt>.
285d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
285e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 um length of an
285f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
28600 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a n bytes.</dd>)^.
28610 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
28620 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 IMIT_COLUMN]] ^(
28630 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28640 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 _COLUMN</dt>.**
28650 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
28660 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
28670 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 s in a table def
28680 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 inition or in th
28690 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 e.** result set
286a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 of a [SELECT] or
286b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
286c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
286d0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 n an index.** or
286e0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 in an ORDER BY
286f0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 or GROUP BY clau
28700 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a se.</dd>)^.**.**
28710 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
28720 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c EXPR_DEPTH]] ^(<
28730 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
28740 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a EXPR_DEPTH</dt>.
28750 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
28760 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 um depth of the
28770 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e parse tree on an
28780 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 y expression.</d
28790 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
287a0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
287b0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 ND_SELECT]] ^(<d
287c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 t>SQLITE_LIMIT_C
287d0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f OMPOUND_SELECT</
287e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
287f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
28800 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 terms in a comp
28810 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 ound SELECT stat
28820 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ement.</dd>)^.**
28830 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
28840 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c IT_VDBE_OP]] ^(<
28850 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
28860 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
28870 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
28880 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
28890 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
288a0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
288b0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
288c0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
288d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 statement. This
288e0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 limit is not cu
288f0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 rrently.** enfor
28900 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 ced, though that
28910 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 might be added
28920 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
28930 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
28940 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ite.</dd>)^.**.*
28950 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
28960 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 _FUNCTION_ARG]]
28970 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
28980 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c IT_FUNCTION_ARG<
28990 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
289a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
289b0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 f arguments on a
289c0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 function.</dd>)
289d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
289e0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d _LIMIT_ATTACHED]
289f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
28a00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 IMIT_ATTACHED</d
28a10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
28a20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
28a30 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 [ATTACH | attach
28a40 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e ed databases].)^
28a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
28a60 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
28a70 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d PATTERN_LENGTH]]
28a80 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
28a90 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
28aa0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a ERN_LENGTH</dt>.
28ab0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
28ac0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 um length of the
28ad0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e pattern argumen
28ae0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 t to the [LIKE]
28af0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 or.** [GLOB] ope
28b00 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a rators.</dd>)^.*
28b10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
28b20 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
28b30 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 BER]].** ^(<dt>S
28b40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
28b50 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e ABLE_NUMBER</dt>
28b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
28b70 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 mum index number
28b80 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 of any [paramet
28b90 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 er] in an SQL st
28ba0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a atement.)^.**.**
28bb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
28bc0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 TRIGGER_DEPTH]]
28bd0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
28be0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
28bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
28c00 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
28c10 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 f recursion for
28c20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e triggers.</dd>)^
28c30 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
28c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
28c50 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 T_LENGTH
28c60 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 0.#d
28c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
28c80 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 IT_SQL_LENGTH
28c90 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
28ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
28cb0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 MIT_COLUMN
28cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
28cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
28ce0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 IMIT_EXPR_DEPTH
28cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
28d00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
28d10 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
28d20 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
28d30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
28d40 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 _LIMIT_VDBE_OP
28d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
28d60 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
28d70 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
28d80 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 _ARG
28d90 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
28da0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
28db0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
28dc0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
28dd0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
28de0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 ATTERN_LENGTH
28df0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
28e00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
28e10 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 BLE_NUMBER
28e20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
28e30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
28e40 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 GER_DEPTH
28e50 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 10../*.** C
28e60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 API3REF: Compili
28e70 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d ng An SQL Statem
28e80 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ent.** KEYWORDS:
28e90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 {SQL statement
28ea0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 compiler}.**.**
28eb0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
28ec0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
28ed0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
28ee0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
28ef0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
28f00 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
28f10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
28f20 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
28f30 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 ment, "db", is a
28f40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
28f50 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 ction] obtained
28f60 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 from a.** prior
28f70 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
28f80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
28f90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
28fa0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b en_v2()] or.** [
28fb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
28fc0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 ]. The database
28fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
28fe0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 not have been c
28ff0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
29000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
29010 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 , "zSql", is the
29020 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
29030 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
29040 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
29050 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
29060 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
29070 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
29080 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29090 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
290a0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 se UTF-8, and sq
290b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
290c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
290d0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
290e0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a use UTF-16..**.*
290f0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 * ^If the nByte
29100 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 argument is less
29110 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e than zero, then
29120 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
29130 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
29140 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
29150 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e . ^If nByte is n
29160 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
29170 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 n it is the maxi
29180 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 mum.** number of
29190 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f bytes read fro
291a0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e m zSql. ^When n
291b0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
291c0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 tive, the.** zSq
291d0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 l string ends at
291e0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 either the firs
291f0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 t '\000' or '\u0
29200 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 000' character o
29210 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 r.** the nByte-t
29220 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 h byte, whicheve
29230 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 r comes first. I
29240 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f f the caller kno
29250 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 ws.** that the s
29260 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 upplied string i
29270 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 s nul-terminated
29280 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 , then there is
29290 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f a small.** perfo
292a0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 rmance advantage
292b0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 to be gained by
292c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 passing an nByt
292d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
292e0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 .** is equal to
292f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
29300 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
29310 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
29320 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
29330 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 nul-terminator b
29340 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 ytes as this sav
29350 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 es SQLite from h
29360 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 aving to.** make
29370 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 a copy of the i
29380 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a nput string..**.
29390 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 ** ^If pzTail is
293a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
293b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
293c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
293d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
293e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
293f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
29400 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
29410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
29420 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
29430 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
29440 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
29450 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
29460 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
29470 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
29480 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 iled..**.** ^*pp
29490 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
294a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
294b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
294c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
294d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
294e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
294f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 step()]. ^If th
29500 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
29510 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
29520 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 ** to NULL. ^If
29530 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 the input text
29540 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 contains no SQL
29550 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 (if the input is
29560 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 an empty.** str
29570 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
29580 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
29590 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a s set to NULL..*
295a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 * The calling pr
295b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
295c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
295d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 ing the compiled
295e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
295f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
29600 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 _finalize()] aft
29610 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 er it has finish
29620 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 ed with it..** p
29630 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 pStmt may not be
29640 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e NULL..**.** ^On
29650 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 success, the sq
29660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
29670 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e family of routin
29680 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
29690 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 E_OK];.** otherw
296a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
296b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
296c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
296d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
296e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
296f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 are16_v2() inter
29700 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 faces are.** rec
29710 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c ommended for all
29720 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 new programs. T
29730 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 he two older int
29740 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 erfaces are reta
29750 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b ined.** for back
29760 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
29770 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 ity, but their u
29780 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 se is discourage
29790 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 d..** ^In the "v
297a0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
297b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
297c0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
297d0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
297e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
297f0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
29800 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
29810 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
29820 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
29830 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
29840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
29850 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 .** behave diffe
29860 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 rently in three
29870 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
29880 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
29890 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
298a0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 ema changes, ins
298b0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e tead of returnin
298c0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 g [SQLITE_SCHEMA
298d0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 ] as it.** alway
298e0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 s used to do, [s
298f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
29900 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
29910 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 y recompile the
29920 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
29930 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 and try to run
29940 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c it again..** </l
29950 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
29960 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 ^When an error
29970 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 occurs, [sqlite3
29980 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 _step()] will re
29990 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 turn one of the
299a0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 detailed.** [err
299b0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 or codes] or [ex
299c0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
299d0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 es]. ^The legac
299e0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
299f0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hat.** [sqlite3_
29a00 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e step()] would on
29a10 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 ly return a gene
29a20 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ric [SQLITE_ERRO
29a30 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a R] result code.*
29a40 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 * and the applic
29a50 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 ation would have
29a60 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e to make a secon
29a70 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 d call to [sqlit
29a80 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 e3_reset()].** i
29a90 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
29aa0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 the underlying c
29ab0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 ause of the prob
29ac0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 lem. With the "v
29ad0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 2" prepare.** in
29ae0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e terfaces, the un
29af0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 derlying reason
29b00 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 for the error is
29b10 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
29b20 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a ately..** </li>.
29b30 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 **.** <li>.** ^I
29b40 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 f the specific v
29b50 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 alue bound to [p
29b60 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 arameter | host
29b70 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
29b80 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 e .** WHERE clau
29b90 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e se might influen
29ba0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 ce the choice of
29bb0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 query plan for
29bc0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 a statement,.**
29bd0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 then the stateme
29be0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d nt will be autom
29bf0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
29c00 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 led, as if there
29c10 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 had been .** a
29c20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f schema change, o
29c30 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 n the first [sq
29c40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
29c50 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ll following any
29c60 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 change.** to th
29c70 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
29c80 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d text | bindings]
29c90 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 of that [parame
29ca0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 ter]. .** ^The s
29cb0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 pecific value of
29cc0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 WHERE-clause [p
29cd0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 arameter] might
29ce0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a influence the .*
29cf0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 * choice of quer
29d00 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 y plan if the pa
29d10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c rameter is the l
29d20 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 eft-hand side of
29d30 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 a [LIKE].** or
29d40 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 [GLOB] operator
29d50 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 or if the parame
29d60 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 ter is compared
29d70 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f to an indexed co
29d80 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 lumn.** and the
29d90 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 [SQLITE_ENABLE_S
29da0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 TAT3] compile-ti
29db0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 me option is ena
29dc0 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a bled..** the .**
29dd0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a </li>.** </ol>.
29de0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
29df0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
29e00 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
29e10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
29e20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
29e30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
29e40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
29e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
29e60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
29e70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
29e80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
29e90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
29ea0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
29eb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
29ec0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
29ed0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
29ee0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
29ef0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
29f00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
29f10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
29f20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
29f30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29f40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29f50 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
29f60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
29f70 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
29f80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
29f90 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
29fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
29fb0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
29fc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
29fd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
29fe0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
29ff0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2a000 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2a010 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2a020 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2a030 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2a040 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
2a050 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2a060 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2a070 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2a080 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2a090 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2a0a0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
2a0b0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2a0c0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2a0d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2a0e0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2a0f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2a100 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
2a110 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2a120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2a130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2a140 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2a150 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2a160 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2a170 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2a180 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2a190 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
2a1a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2a1b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2a1c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2a1d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2a1e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
2a1f0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 e16_v2(. sqlite
2a200 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
2a210 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
2a220 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2a230 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 void *zSql,
2a240 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
2a250 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 nt, UTF-16 encod
2a260 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
2a270 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
2a280 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
2a290 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
2a2a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
2a2b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2a2c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2a2d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2a2e0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 onst void **pzTa
2a2f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2a300 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2a310 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2a320 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2a330 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 PI3REF: Retrievi
2a340 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c ng Statement SQL
2a350 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 .**.** ^This int
2a360 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2a370 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 ed to retrieve a
2a380 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 saved copy of t
2a390 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 he original.** S
2a3a0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 QL text used to
2a3b0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 create a [prepar
2a3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 ed statement] if
2a3d0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
2a3e0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 was.** compiled
2a3f0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
2a400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2a410 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2a420 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
2a430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2a440 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
2a450 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
2a460 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2a470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2a480 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
2a490 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 L Statement Writ
2a4a0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a es The Database.
2a4b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a4c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2a4d0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
2a4e0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
2a4f0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
2a500 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
2a510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2a520 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
2a530 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
2a540 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2a550 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2a560 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
2a570 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
2a580 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2a590 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
2a5a0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
2a5b0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
2a5c0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
2a5d0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
2a5e0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
2a5f0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
2a600 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2a610 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
2a620 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
2a630 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
2a640 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
2a650 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
2a660 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
2a670 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
2a680 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
2a690 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
2a6a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
2a6b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
2a6c0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
2a6d0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
2a6e0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
2a6f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
2a700 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
2a710 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2a720 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
2a730 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2a740 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
2a750 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
2a760 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
2a770 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
2a780 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
2a790 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
2a7a0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
2a7b0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
2a7c0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
2a7d0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
2a7e0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
2a7f0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
2a800 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
2a810 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
2a820 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
2a830 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
2a840 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
2a850 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
2a860 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
2a870 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
2a880 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
2a890 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
2a8a0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
2a8b0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
2a8c0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
2a8d0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
2a8e0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
2a8f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
2a900 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
2a910 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
2a920 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
2a930 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
2a940 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
2a950 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
2a960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
2a970 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
2a980 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
2a990 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
2a9a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
2a9b0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 s on disk..*/.SQ
2a9c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2a9d0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2a9e0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ly(sqlite3_stmt
2a9f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2aa00 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
2aa10 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 ine If A Prepare
2aa20 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 d Statement Has
2aa30 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a Been Reset.**.**
2aa40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
2aa50 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 mt_busy(S) inter
2aa60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2aa70 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 e (non-zero) if
2aa80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2aa90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
2aaa0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 s been stepped a
2aab0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 t least once usi
2aac0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
2aad0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 step(S)] but has
2aae0 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 not run to comp
2aaf0 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 letion and/or ha
2ab00 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 s not .** been r
2ab10 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 eset using [sqli
2ab20 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 te3_reset(S)].
2ab30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2ab40 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 t_busy(S).** int
2ab50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 erface returns f
2ab60 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e alse if S is a N
2ab70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 ULL pointer. If
2ab80 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 S is not a .**
2ab90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
2aba0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 is not a pointe
2abb0 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 r to a valid [pr
2abc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2abd0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 ].** object, the
2abe0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
2abf0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2ac00 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 probably undesir
2ac10 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 able..**.** This
2ac20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
2ac30 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e e used in combin
2ac40 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e ation [sqlite3_n
2ac50 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 ext_stmt()].** t
2ac60 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 o locate all pre
2ac70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2ac80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2ac90 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 a database .**
2aca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2acb0 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 are in need of b
2acc0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 eing reset. Thi
2acd0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a s can be used,.*
2ace0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 * for example, i
2acf0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 n diagnostic rou
2ad00 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 tines to search
2ad10 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a for prepared .**
2ad20 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
2ad30 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 are holding a t
2ad40 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e ransaction open.
2ad50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2ad60 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
2ad70 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d busy(sqlite3_stm
2ad80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2ad90 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
2ada0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
2adb0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
2adc0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
2add0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
2ade0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2adf0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
2ae00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
2ae10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2ae20 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
2ae30 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
2ae40 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
2ae50 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
2ae60 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
2ae70 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
2ae80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
2ae90 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e es it stores. ^
2aea0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
2aeb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2aec0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
2aed0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
2aee0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
2aef0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
2af00 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
2af10 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
2af20 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
2af30 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
2af40 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
2af50 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
2af60 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2af70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2af80 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
2af90 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
2afa0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
2afb0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
2afc0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
2afd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2afe0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
2aff0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
2b000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
2b010 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
2b020 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
2b030 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
2b040 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2b050 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
2b060 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
2b070 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
2b080 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
2b090 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
2b0a0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
2b0b0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 eld. An interna
2b0c0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
2b0d0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
2b0e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2b0f0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
2b100 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
2b110 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
2b120 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2b130 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
2b140 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
2b150 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
2b160 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
2b170 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
2b180 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
2b190 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2b1a0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
2b1b0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
2b1c0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
2b1d0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
2b1e0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
2b1f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2b200 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
2b210 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
2b220 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
2b230 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
2b240 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
2b250 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
2b260 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
2b270 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2b280 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
2b290 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
2b2a0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
2b2b0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
2b2c0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
2b2d0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
2b2e0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
2b2f0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
2b300 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
2b310 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
2b320 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
2b330 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2b340 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
2b350 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 ven when not str
2b360 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a ictly required..
2b370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2b380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2b390 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
2b3a0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
2b3b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
2b3c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
2b3d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2b3e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2b3f0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
2b400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2b410 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
2b420 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2b430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2b440 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
2b450 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
2b460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2b470 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
2b480 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
2b490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
2b4a0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
2b4b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
2b4c0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
2b4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
2b4e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
2b4f0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
2b500 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
2b510 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
2b520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2b530 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
2b540 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
2b550 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
2b560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2b570 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
2b580 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a ontext Object.**
2b590 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 .** The context
2b5a0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 in which an SQL
2b5b0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 function execute
2b5c0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 s is stored in a
2b5d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e n.** sqlite3_con
2b5e0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 text object. ^A
2b5f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
2b600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
2b610 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
2b620 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
2b630 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
2b640 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2b650 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
2b660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2b670 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2b680 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2b690 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
2b6a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
2b6b0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
2b6c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
2b6d0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
2b6e0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
2b6f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2b700 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
2b710 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
2b720 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2b730 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
2b740 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
2b750 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
2b760 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
2b770 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
2b780 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2b790 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
2b7a0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
2b7b0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
2b7c0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
2b7d0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
2b7e0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b Statements.** K
2b7f0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
2b800 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
2b810 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
2b820 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2b830 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2b840 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
2b850 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
2b860 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
2b870 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ng}.**.** ^(In t
2b880 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
2b890 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b text input to [
2b8a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2b8b0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
2b8c0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
2b8d0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
2b8e0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 ced by a [parame
2b8f0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 ter] that matche
2b900 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 s one of followi
2b910 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a ng.** templates:
2b920 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2b930 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 li> ?.** <li>
2b940 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 ?NNN.** <li> :V
2b950 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 VV.** <li> @VVV
2b960 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a .** <li> $VVV.*
2b970 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2b980 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 the templates a
2b990 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 bove, NNN repres
2b9a0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 ents an integer
2b9b0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 literal,.** and
2b9c0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 VVV represents a
2b9d0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 n alphanumeric i
2b9e0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 dentifier.)^ ^T
2b9f0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
2ba00 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
2ba10 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
2ba20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
2ba30 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
2ba40 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
2ba50 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
2ba60 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2ba70 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
2ba80 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
2ba90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
2baa0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
2bab0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
2bac0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
2bad0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
2bae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
2baf0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
2bb00 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
2bb10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2bb20 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
2bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
2bb40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2bb50 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2bb60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
2bb70 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 o be set..** ^Th
2bb80 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
2bb90 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
2bba0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 index of 1. ^Wh
2bbb0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
2bbc0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
2bbd0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
2bbe0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
2bbf0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
2bc00 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
2bc10 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
2bc20 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
2bc30 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
2bc40 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e ^The index for n
2bc50 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
2bc60 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
2bc70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
2bc80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2bc90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
2bca0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
2bcb0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f ^The index.** fo
2bcc0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
2bcd0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
2bce0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 of NNN..** ^The
2bcf0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
2bd00 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
2bd10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
2bd20 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
2bd30 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
2bd40 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
2bd50 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
2bd60 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e e: 999)..**.** ^
2bd70 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
2bd80 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
2bd90 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
2bda0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2bdb0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
2bdc0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
2bdd0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
2bde0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
2bdf0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
2be00 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
2be10 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
2be20 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
2be30 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2be40 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
2be50 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
2be60 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
2be70 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
2be80 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
2be90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2bea0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
2beb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2bec0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
2bed0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
2bee0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
2bef0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
2bf00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2bf10 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
2bf20 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
2bf30 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
2bf40 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
2bf50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2bf60 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
2bf70 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
2bf80 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
2bf90 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
2bfa0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
2bfc0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
2bfd0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
2bfe0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2bff0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 _text16() then t
2c000 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
2c010 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
2c020 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
2c030 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
2c040 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
2c050 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
2c060 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
2c070 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
2c080 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
2c090 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
2c0a0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
2c0b0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
2c0c0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
2c0d0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
2c0e0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
2c0f0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
2c100 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
2c110 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
2c120 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
2c130 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
2c140 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
2c150 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
2c160 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2c170 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2c180 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2c190 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
2c1a0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
2c1b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
2c1c0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
2c1d0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
2c1e0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
2c1f0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
2c200 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
2c210 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
2c220 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
2c230 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
2c240 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
2c250 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
2c260 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
2c270 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
2c280 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
2c290 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
2c2a0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
2c2b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
2c2c0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
2c2d0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
2c2e0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
2c2f0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
2c300 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
2c310 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
2c320 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
2c330 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
2c340 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
2c350 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
2c360 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
2c370 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
2c380 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
2c390 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
2c3a0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
2c3b0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
2c3c0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
2c3d0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
2c3e0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
2c3f0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
2c400 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2c410 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
2c420 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
2c430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
2c440 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
2c450 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
2c460 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
2c470 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
2c480 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
2c490 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
2c4a0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
2c4b0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
2c4c0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
2c4d0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
2c4e0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
2c4f0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
2c500 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
2c510 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
2c520 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
2c530 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
2c540 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
2c550 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
2c560 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
2c570 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
2c580 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
2c590 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
2c5a0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
2c5b0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
2c5c0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
2c5d0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
2c5e0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
2c5f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2c600 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
2c610 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
2c620 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
2c630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c640 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
2c650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c660 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
2c670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2c680 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
2c690 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
2c6a0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
2c6b0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
2c6c0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
2c6d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
2c6e0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
2c6f0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
2c700 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
2c710 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2c720 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
2c730 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
2c740 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
2c750 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2c760 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
2c770 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
2c780 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
2c790 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
2c7a0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
2c7b0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
2c7c0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
2c7d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
2c7e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
2c7f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
2c800 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
2c810 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
2c820 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
2c830 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
2c840 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
2c850 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
2c860 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
2c870 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
2c880 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
2c890 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
2c8a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
2c8b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
2c8c0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
2c8d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2c8e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2c8f0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
2c900 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2c910 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
2c920 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
2c930 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2c940 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2c950 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2c960 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c e3_bind_blob(sql
2c970 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2c980 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
2c990 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
2c9a0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
2c9b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
2c9c0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
2c9d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
2c9e0 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ble);.SQLITE_API
2c9f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
2ca00 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
2ca10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
2ca20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2ca30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 qlite3_bind_int6
2ca40 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2ca50 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e int, sqlite3_in
2ca60 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 t64);.SQLITE_API
2ca70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
2ca80 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
2ca90 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 tmt*, int);.SQLI
2caa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2cab0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c e3_bind_text(sql
2cac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2cad0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
2cae0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
2caf0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
2cb00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
2cb10 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 d_text16(sqlite3
2cb20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2cb30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
2cb40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2cb50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2cb60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2cb70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2cb80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 int, const sqli
2cb90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
2cba0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2cbb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2cbc0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2cbd0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f int, int n);../
2cbe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2cbf0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
2cc00 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 ameters.**.** ^T
2cc10 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
2cc20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 be used to find
2cc30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 the number of [S
2cc40 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a QL parameters].*
2cc50 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 * in a [prepared
2cc60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 statement]. SQ
2cc70 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 L parameters are
2cc80 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a tokens of the.*
2cc90 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e * form "?", "?NN
2cca0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 N", ":AAA", "$AA
2ccb0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 A", or "@AAA" th
2ccc0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 at serve as.** p
2ccd0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
2cce0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 values that are
2ccf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2cd00 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 ob | bound].** t
2cd10 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 o the parameters
2cd20 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 at a later time
2cd30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 ..**.** ^(This r
2cd40 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
2cd50 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
2cd60 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
2cd70 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 (rightmost).**
2cd80 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 parameter. For a
2cd90 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 ll forms except
2cda0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 ?NNN, this will
2cdb0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 correspond to th
2cdc0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 e.** number of u
2cdd0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 nique parameters
2cde0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 . If parameters
2cdf0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 of the ?NNN for
2ce00 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 m are used,.** t
2ce10 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 here may be gaps
2ce20 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a in the list.)^.
2ce30 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2ce40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2ce50 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
2ce60 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2ce70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2ce80 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ame()], and.** [
2ce90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2cea0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2ceb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2cec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2ced0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2cee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
2cef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2cf00 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
2cf10 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
2cf20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2cf30 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2cf40 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
2cf50 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
2cf60 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
2cf70 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
2cf80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
2cf90 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
2cfa0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
2cfb0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2cfc0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
2cfd0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
2cfe0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
2cff0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
2d000 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
2d010 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
2d020 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
2d030 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2d040 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2d050 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
2d060 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
2d070 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
2d080 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
2d090 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
2d0a0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
2d0b0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
2d0c0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
2d0d0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
2d0e0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
2d0f0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
2d100 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
2d110 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
2d120 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
2d130 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
2d140 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
2d150 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
2d160 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
2d170 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
2d180 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
2d190 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
2d1a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
2d1b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
2d1c0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
2d1d0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
2d1e0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
2d1f0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
2d200 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
2d210 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
2d220 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
2d230 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
2d240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
2d250 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2d260 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2d270 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
2d280 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
2d290 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
2d2a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
2d2b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2d2c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
2d2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2d2e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2d2f0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2d300 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
2d310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2d320 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
2d330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
2d340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d350 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
2d360 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
2d370 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 en Name.**.** ^R
2d380 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
2d390 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 of an SQL parame
2d3a0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 ter given its na
2d3b0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 me. ^The.** ind
2d3c0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
2d3d0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
2d3e0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
2d3f0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
2d400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
2d410 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2d420 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f ind()]. ^A zero
2d430 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
2d440 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
2d450 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
2d460 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 d. ^The paramet
2d470 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
2d480 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
2d490 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
2d4a0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
2d4b0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
2d4c0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
2d4d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
2d4e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2d4f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2d500 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2d510 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2d520 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
2d530 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2d540 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
2d550 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2d560 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2d570 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2d580 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
2d590 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2d5a0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
2d5b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
2d5c0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
2d5d0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
2d5e0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
2d5f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2d600 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 t.**.** ^Contrar
2d610 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
2d620 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
2d630 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
2d640 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
2d650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2d660 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
2d670 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
2d680 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2d690 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 ^Use this routi
2d6a0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 ne to reset all
2d6b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
2d6c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 to NULL..*/.SQLI
2d6d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2d6e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
2d6f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 s(sqlite3_stmt*)
2d700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d710 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c F: Number Of Col
2d720 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 umns In A Result
2d730 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 Set.**.** ^Retu
2d740 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
2d750 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2d760 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
2d770 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
2d780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d790 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e t]. ^This routin
2d7a0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 e returns 0 if p
2d7b0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a Stmt is an SQL.*
2d7c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 * statement that
2d7d0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
2d7e0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
2d7f0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
2d800 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2d810 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
2d820 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 ount()].*/.SQLIT
2d830 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2d840 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
2d850 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2d860 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2d870 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
2d880 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
2d890 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 et.**.** ^These
2d8a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
2d8b0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 the name assigne
2d8c0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 d to a particula
2d8d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 r column.** in t
2d8e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 he result set of
2d8f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
2d900 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c ement. ^The sql
2d910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2d920 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
2d930 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2d940 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
2d950 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
2d960 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 ing.** and sqlit
2d970 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2d980 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
2d990 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 nter to a zero-t
2d9a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
2d9b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2d9c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2d9d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
2d9e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2d9f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
2da00 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
2da10 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 atement. ^The se
2da20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
2da30 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 s the.** column
2da40 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 number. ^The le
2da50 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 ftmost column is
2da60 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a number 0..**.**
2da70 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2da80 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 tring pointer is
2da90 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 valid until eit
2daa0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 her the [prepare
2dab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2dac0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 is destroyed by
2dad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2dae0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
2daf0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2db00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
2db10 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
2db20 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
2db30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2db40 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
2db50 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
2db60 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 l the next call
2db70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f to.** sqlite3_co
2db80 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 lumn_name() or s
2db90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2dba0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 me16() on the sa
2dbb0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
2dbc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
2dbd0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
2dbe0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
2dbf0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
2dc00 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
2dc10 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
2dc20 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
2dc30 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
2dc40 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
2dc50 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
2dc60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
2dc70 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f e of a result co
2dc80 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 lumn is the valu
2dc90 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c e of the "AS" cl
2dca0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 ause for.** that
2dcb0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 column, if ther
2dcc0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 e is an AS claus
2dcd0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 e. If there is
2dce0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 no AS clause.**
2dcf0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 then the name of
2dd00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 the column is u
2dd10 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d nspecified and m
2dd20 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a ay change from.*
2dd30 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 * one release of
2dd40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e SQLite to the n
2dd50 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ext..*/.SQLITE_A
2dd60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
2dd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
2dd80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2dd90 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
2dda0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2ddb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2ddc0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2ddd0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
2dde0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2ddf0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
2de00 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2de10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2de20 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2de30 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2de40 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2de50 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2de60 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2de70 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2de80 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2de90 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2dea0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2deb0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2dec0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2ded0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2dee0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2def0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2df00 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2df10 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2df20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2df30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2df40 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2df50 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2df60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2df70 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2df80 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2df90 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2dfa0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2dfb0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2dfc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2dfd0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2dfe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2dff0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2e000 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2e010 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2e020 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2e030 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2e040 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2e050 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2e060 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2e070 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2e080 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2e090 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2e0a0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2e0b0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2e0c0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2e0d0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2e0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2e0f0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2e100 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2e110 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2e120 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2e130 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2e140 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2e150 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2e160 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2e170 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2e180 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2e190 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2e1a0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2e1b0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2e1c0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2e1d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2e1e0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2e1f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2e200 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2e210 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2e220 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2e230 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2e240 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2e250 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2e260 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2e270 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2e280 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2e290 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2e2a0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2e2b0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2e2c0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2e2d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2e2e0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2e2f0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2e300 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2e310 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2e320 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2e330 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2e340 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2e350 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2e360 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2e370 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2e380 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2e390 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2e3a0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2e3b0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2e3c0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2e3d0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2e3e0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2e3f0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2e400 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2e410 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2e420 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2e430 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2e440 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2e450 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2e460 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2e470 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2e480 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2e490 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2e4a0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2e4b0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2e4c0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2e4d0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2e4e0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2e4f0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2e500 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2e510 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2e520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
2e530 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
2e540 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2e550 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
2e560 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2e570 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2e580 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2e590 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
2e5a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2e5b0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
2e5c0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
2e5d0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
2e5e0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
2e5f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2e600 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
2e610 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
2e620 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2e630 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2e640 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
2e650 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
2e660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2e670 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 tabase_name(sqli
2e680 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2e690 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2e6a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2e6b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
2e6c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2e6d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2e6e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
2e6f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2e700 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 table_name(sqlit
2e710 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2e720 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2e730 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2e740 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
2e750 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2e760 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2e770 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
2e780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
2e790 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f in_name(sqlite3_
2e7a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2e7b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2e7c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2e7d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 n_origin_name16(
2e7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2e7f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e800 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 REF: Declared Da
2e810 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 tatype Of A Quer
2e820 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
2e830 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
2e840 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
2e850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2e860 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
2e870 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
2e880 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
2e890 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2e8a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
2e8b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
2e8c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
2e8d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
2e8e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
2e8f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
2e900 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
2e910 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
2e920 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
2e930 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
2e940 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
2e950 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2e960 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
2e970 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
2e980 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
2e990 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
2e9a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
2e9b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2e9c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
2e9d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
2e9e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
2e9f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
2ea00 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
2ea10 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
2ea20 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
2ea30 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
2ea40 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
2ea50 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
2ea60 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
2ea70 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
2ea80 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
2ea90 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
2eaa0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
2eab0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
2eac0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
2ead0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
2eae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2eaf0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
2eb00 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
2eb10 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
2eb20 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
2eb30 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
2eb40 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
2eb50 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
2eb60 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
2eb70 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
2eb80 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
2eb90 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
2eba0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
2ebb0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
2ebc0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
2ebd0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
2ebe0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
2ebf0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
2ec00 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
2ec10 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
2ec20 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
2ec30 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
2ec40 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
2ec50 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
2ec60 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
2ec70 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
2ec80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2ec90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
2eca0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
2ecb0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
2ecc0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2ecd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2ece0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2ecf0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
2ed00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
2ed10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
2ed20 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
2ed30 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 tement.**.** Aft
2ed40 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 er a [prepared s
2ed50 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 tatement] has be
2ed60 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e en prepared usin
2ed70 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c g either.** [sql
2ed80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2ed90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
2eda0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
2edb0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 r one of the leg
2edc0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
2edd0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
2ede0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 re()] or [sqlite
2edf0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 3_prepare16()],
2ee00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a this function.**
2ee10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
2ee20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
2ee30 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 s to evaluate th
2ee40 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a e statement..**.
2ee50 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f ** The details o
2ee60 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f f the behavior o
2ee70 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 f the sqlite3_st
2ee80 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 ep() interface d
2ee90 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 epend.** on whet
2eea0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e her the statemen
2eeb0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 t was prepared u
2eec0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 sing the newer "
2eed0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a v2" interface.**
2eee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2eef0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
2ef00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2ef10 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 2()] or the olde
2ef20 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 r legacy.** inte
2ef30 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 rface [sqlite3_p
2ef40 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
2ef50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ef60 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 ()]. The use of
2ef70 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 the.** new "v2"
2ef80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
2ef90 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 commended for ne
2efa0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 w applications b
2efb0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a ut the legacy.**
2efc0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
2efd0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 continue to be s
2efe0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 upported..**.**
2eff0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 ^In the legacy i
2f000 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 nterface, the re
2f010 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 turn value will
2f020 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 be either [SQLIT
2f030 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c E_BUSY],.** [SQL
2f040 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 ITE_DONE], [SQLI
2f050 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 TE_ROW], [SQLITE
2f060 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c _ERROR], or [SQL
2f070 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 ITE_MISUSE]..**
2f080 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 ^With the "v2" i
2f090 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
2f0a0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
2f0b0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
2f0c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
2f0d0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
2f0e0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
2f0f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 l..**.** ^[SQLIT
2f100 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 E_BUSY] means th
2f110 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 at the database
2f120 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c engine was unabl
2f130 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 e to acquire the
2f140 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 .** database loc
2f150 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 ks it needs to d
2f160 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 o its job. ^If
2f170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2f180 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f a [COMMIT].** o
2f190 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 r occurs outside
2f1a0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 of an explicit
2f1b0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
2f1c0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 n you can retry
2f1d0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
2f1e0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d . If the statem
2f1f0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f ent is not a [CO
2f200 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 MMIT] and occurs
2f210 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 within an.** ex
2f220 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
2f230 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 on then you shou
2f240 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 ld rollback the
2f250 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f transaction befo
2f260 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 re.** continuing
2f270 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 ..**.** ^[SQLITE
2f280 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 _DONE] means tha
2f290 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
2f2a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
2f2b0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 cuting.** succes
2f2c0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 sfully. sqlite3
2f2d0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
2f2e0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
2f2f0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 in on this virtu
2f300 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 al.** machine wi
2f310 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c thout first call
2f320 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
2f330 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 et()] to reset t
2f340 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 he virtual.** ma
2f350 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 chine back to it
2f360 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e s initial state.
2f370 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 .**.** ^If the S
2f380 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 QL statement bei
2f390 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 ng executed retu
2f3a0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 rns any data, th
2f3b0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a en [SQLITE_ROW].
2f3c0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 ** is returned e
2f3d0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 ach time a new r
2f3e0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 ow of data is re
2f3f0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 ady for processi
2f400 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ng by the.** cal
2f410 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 ler. The values
2f420 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 may be accessed
2f430 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d using the [colum
2f440 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
2f450 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ns]..** sqlite3_
2f460 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 step() is called
2f470 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 again to retrie
2f480 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 ve the next row
2f490 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e of data..**.** ^
2f4a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d [SQLITE_ERROR] m
2f4b0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d eans that a run-
2f4c0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 time error (such
2f4d0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 as a constraint
2f4e0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 .** violation) h
2f4f0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 as occurred. sq
2f500 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
2f510 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
2f520 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 d again on.** th
2f530 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 e VM. More infor
2f540 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f mation may be fo
2f550 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b und by calling [
2f560 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
2f570 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
2f580 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2f590 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 , a more specifi
2f5a0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f c error code (fo
2f5b0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 r example,.** [S
2f5c0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
2f5d0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 , [SQLITE_SCHEMA
2f5e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 ], [SQLITE_CORRU
2f5f0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 PT], and so fort
2f600 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 h).** can be obt
2f610 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 ained by calling
2f620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f630 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 )] on the.** [pr
2f640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f650 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 ]. ^In the "v2"
2f660 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
2f670 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
2f680 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
2f690 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
2f6a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
2f6b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
2f6c0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
2f6d0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
2f6e0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
2f6f0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
2f700 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
2f710 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
2f720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2f730 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a ent] that has.**
2f740 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 already been [s
2f750 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
2f760 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 | finalized] or
2f770 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a on one that had.
2f780 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
2f790 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
2f7a0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
2f7b0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
2f7c0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
2f7d0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
2f7e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2f7f0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
2f800 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
2f810 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
2f820 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
2f830 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
2f840 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 For all versions
2f850 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f of SQLite up to
2f860 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 and including 3
2f870 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 .6.23.1, a call
2f880 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
2f890 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 eset()] was requ
2f8a0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 ired after sqlit
2f8b0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e e3_step() return
2f8c0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f ed anything.** o
2f8d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
2f8e0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e E_ROW] before an
2f8f0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 y subsequent inv
2f900 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 ocation of.** sq
2f910 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 lite3_step(). F
2f920 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 ailure to reset
2f930 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
2f940 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a tement using .**
2f950 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f960 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 )] would result
2f970 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 in an [SQLITE_MI
2f980 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f SUSE] return fro
2f990 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 m.** sqlite3_ste
2f9a0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 p(). But after
2f9b0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 version 3.6.23.1
2f9c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
2f9d0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e began.** callin
2f9e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2f9f0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ()] automaticall
2fa00 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d y in this circum
2fa10 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a stance rather.**
2fa20 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 than returning
2fa30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2fa40 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f This is not co
2fa50 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 nsidered a compa
2fa60 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 tibility.** brea
2fa70 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 k because any ap
2fa80 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 plication that e
2fa90 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 ver receives an
2faa0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 SQLITE_MISUSE er
2fab0 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e ror.** is broken
2fac0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 by definition.
2fad0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 The [SQLITE_OMI
2fae0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d T_AUTORESET] com
2faf0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
2fb00 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 .** can be used
2fb10 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c to restore the l
2fb20 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a egacy behavior..
2fb30 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 **.** <b>Goofy I
2fb40 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c nterface Alert:<
2fb50 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 /b> In the legac
2fb60 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
2fb70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a sqlite3_step().
2fb80 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 ** API always re
2fb90 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 turns a generic
2fba0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c error code, [SQL
2fbb0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c ITE_ERROR], foll
2fbc0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 owing any.** err
2fbd0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 or other than [S
2fbe0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 QLITE_BUSY] and
2fbf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2fc00 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a You must call.
2fc10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2fc20 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 t()] or [sqlite3
2fc30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 _finalize()] in
2fc40 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e order to find on
2fc50 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 e of the.** spec
2fc60 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
2fc70 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 s] that better d
2fc80 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
2fc90 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 or..** We admit
2fca0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 that this is a g
2fcb0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 oofy design. Th
2fcc0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 e problem has be
2fcd0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 en fixed.** with
2fce0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
2fcf0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 ace. If you pre
2fd00 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 pare all of your
2fd10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
2fd20 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ** using either
2fd30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2fd40 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
2fd50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2fd60 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 )] instead.** of
2fd70 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
2fd80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2fd90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2fda0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 pare16()] interf
2fdb0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 aces,.** then th
2fdc0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 e more specific
2fdd0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 [error codes] ar
2fde0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 e returned direc
2fdf0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 tly.** by sqlite
2fe00 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 3_step(). The u
2fe10 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 se of the "v2" i
2fe20 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f nterface is reco
2fe30 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 mmended..*/.SQLI
2fe40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2fe50 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f e3_step(sqlite3_
2fe60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
2fe70 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
2fe80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
2fe90 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a result set.**.**
2fea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
2feb0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 ta_count(P) inte
2fec0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
2fed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
2fee0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 mns in the.** cu
2fef0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
2ff00 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b result set of [
2ff10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ff20 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 nt] P..** ^If pr
2ff30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ff40 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 P does not have
2ff50 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 results ready t
2ff60 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 o return.** (via
2ff70 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 calls to the [s
2ff80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2ff90 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t | sqlite3_colu
2ffa0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e mn_*()] of.** in
2ffb0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 terfaces) then s
2ffc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2ffd0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a t(P) returns 0..
2ffe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2fff0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
30000 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 utine also retur
30010 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e ns 0 if P is a N
30020 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 ULL pointer..**
30030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
30040 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
30050 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
30060 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
30070 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
30080 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
30090 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
300a0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
300b0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a data_count(P).**
300c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e will return non
300d0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 -zero if previou
300e0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 s call to [sqlit
300f0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 e3_step](P) retu
30100 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
30110 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 ROW], except in
30120 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 the case of the
30130 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e [PRAGMA incremen
30140 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 tal_vacuum].** w
30150 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 here it always r
30160 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 eturns zero sinc
30170 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 e each step of t
30180 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a hat multi-step.*
30190 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 * pragma returns
301a0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 0 columns of da
301b0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ta..**.** See al
301c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c so: [sqlite3_col
301d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a umn_count()].*/.
301e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
301f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
30200 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
30210 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
30220 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
30230 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a ntal Datatypes.*
30240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
30250 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 TE_TEXT.**.** ^(
30260 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
30270 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
30280 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
30290 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
302a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
302b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
302c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
302d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
302e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
302f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
30300 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
30310 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
30320 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 >)^.**.** These
30330 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
30340 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
30350 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
30360 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
30370 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
30380 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
30390 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
303a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
303b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
303c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
303d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
303e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
303f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
30400 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
30410 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
30420 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
30430 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
30440 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
30450 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
30460 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
30470 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
30480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
30490 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
304a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
304b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
304c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
304d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
304e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
304f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
30500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
30510 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
30520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
30530 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
30540 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f A Query.** KEYWO
30550 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
30560 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
30570 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
30580 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 nes form the "re
30590 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 sult set" interf
305a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ace..**.** ^Thes
305b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
305c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
305d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c out a single col
305e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 umn of the curre
305f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 nt.** result row
30600 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 of a query. ^I
30610 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 n every case the
30620 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
30630 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
30640 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
30650 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
30660 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 is being evalua
30670 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ted (the [sqlite
30680 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 3_stmt*].** that
30690 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 was returned fr
306a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 om [sqlite3_prep
306b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 are_v2()] or one
306c0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 of its variants
306d0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 ).** and the sec
306e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
306f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
30700 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 column for whic
30710 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a h information.**
30720 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
30730 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f ned. ^The leftmo
30740 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 st column of the
30750 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 result set has
30760 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 the index 0..**
30770 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 ^The number of c
30780 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
30790 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 sult can be dete
307a0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 rmined using.**
307b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
307c0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 count()]..**.**
307d0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
307e0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
307f0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
30800 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
30810 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
30820 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
30830 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
30840 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
30850 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
30860 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
30870 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
30880 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
30890 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
308a0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
308b0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
308c0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
308d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
308e0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
308f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
30900 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
30910 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
30920 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
30930 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
30940 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
30950 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
30960 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
30970 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
30980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
30990 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
309a0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
309b0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
309c0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
309d0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
309e0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
309f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
30a00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
30a10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
30a20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
30a30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
30a40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
30a50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
30a60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
30a70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
30a80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
30a90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
30aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
30ab0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
30ac0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
30ad0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
30ae0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
30af0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
30b00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
30b10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
30b20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 ^The returned va
30b30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 lue is one of [S
30b40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a QLITE_INTEGER],.
30b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ** [SQLITE_FLOAT
30b60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d ], [SQLITE_TEXT]
30b70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c , [SQLITE_BLOB],
30b80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c or [SQLITE_NULL
30b90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a ]. The value.**
30ba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
30bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
30bc0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
30bd0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 ngful if no type
30be0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 .** conversions
30bf0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 have occurred as
30c00 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 described below
30c10 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 . After a type
30c20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 conversion,.** t
30c30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
30c40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
30c50 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e umn_type() is un
30c60 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 defined. Future
30c70 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
30c80 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
30c90 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
30ca0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
30cb0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
30cc0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
30cd0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ersion..**.** ^I
30ce0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
30cf0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
30d00 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
30d10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30d20 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ytes().** routin
30d30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
30d40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
30d50 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
30d60 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
30d70 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
30d80 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
30d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30da0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
30db0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
30dc0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
30dd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
30de0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
30df0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
30e00 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
30e10 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
30e20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
30e30 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
30e40 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
30e50 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
30e60 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
30e70 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
30e80 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
30e90 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
30ea0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
30eb0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
30ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
30ed0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 olumn_bytes() re
30ee0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
30ef0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
30f00 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
30f10 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e F-16 string then
30f20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
30f30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a umn_bytes16().**
30f40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
30f50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
30f60 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
30f70 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
30f80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
30f90 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
30fa0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
30fb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
30fc0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
30fd0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 string to UTF-16
30fe0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
30ff0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
31000 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 bytes..** ^If th
31010 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
31020 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
31030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31040 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a bytes16() uses.*
31050 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
31060 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
31070 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
31080 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
31090 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
310a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
310b0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
310c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
310d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
310e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
310f0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 n_bytes16() retu
31100 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
31110 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
31120 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
31130 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
31140 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
31150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
31160 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 ()] do not inclu
31170 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
31180 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 inators at the e
31190 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
311a0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 ing. ^For clari
311b0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 ty: the values r
311c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
311d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
311e0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tes()] and [sqli
311f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31200 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 16()] are the nu
31210 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
31220 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
31230 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
31240 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
31250 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 .** ^Strings ret
31260 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
31270 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
31280 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
31290 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
312a0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
312b0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
312c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
312d0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 ^The return.** v
312e0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
312f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
31300 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
31310 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c h BLOB is a NULL
31320 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
31330 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 ^The object retu
31340 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
31350 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
31360 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
31370 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
31380 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 alue] object. A
31390 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
313a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
313b0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ct.** may only b
313c0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c e used with [sql
313d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
313e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
313f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
31400 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
31410 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
31420 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
31430 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
31440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
31450 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
31460 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
31470 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
31480 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
31490 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c ike [sqlite3_val
314a0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 ue_int()], [sqli
314b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
314c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
314d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
314e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
314f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
31500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
31510 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 utines attempt t
31520 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
31530 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 lue where approp
31540 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 riate. ^For.**
31550 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
31560 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
31570 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
31580 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
31590 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
315a0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
315b0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
315c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
315d0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
315e0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
315f0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
31600 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
31610 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
31620 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
31630 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
31640 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
31650 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
31660 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
31670 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
31680 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
31690 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
316a0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
316b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
316c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
316d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
316e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
316f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
31700 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
31710 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
31720 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
31730 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
31740 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
31750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
31760 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
31770 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
31780 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
31790 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
317a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
317b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
317c0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
317d0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
317e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
317f0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
31800 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
31810 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
31820 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
31830 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
31840 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
31850 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
31860 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
31870 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
31880 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
31890 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
318a0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
318b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
318c0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
318d0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
318e0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
318f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
31900 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
31910 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
31920 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
31930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
31940 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
31950 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
31960 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
31970 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
31980 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
31990 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
319a0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
319b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
319c0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
319d0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
319e0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
319f0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
31a00 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
31a10 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
31a20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
31a30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
31a40 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
31a50 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
31a60 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
31a70 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
31a80 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
31a90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
31aa0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
31ab0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
31ac0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te>)^.**.** The
31ad0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 table above make
31ae0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 s reference to s
31af0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
31b00 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 y functions atoi
31b10 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 ().** and atof()
31b20 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e . SQLite does n
31b30 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 ot really use th
31b40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
31b50 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 It has its.** ow
31b60 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 n equivalent int
31b70 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
31b80 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
31b90 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
31ba0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
31bb0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
31bc0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
31bd0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
31be0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
31bf0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
31c00 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
31c10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
31c20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
31c30 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
31c40 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
31c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
31c60 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
31c70 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
31c80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
31c90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
31ca0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
31cb0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 ..** Type conver
31cc0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 sions and pointe
31cd0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 r invalidations
31ce0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 might occur.** i
31cf0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
31d00 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c cases:.**.** <ul
31d10 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
31d20 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
31d30 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
31d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
31d50 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
31d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
31d70 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
31d80 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
31d90 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
31da0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 need to be adde
31db0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e d to the string.
31dc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
31dd0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
31de0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 t is UTF-8 text
31df0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
31e00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a mn_bytes16() or.
31e10 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
31e20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
31e30 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
31e40 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
31e50 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
31e60 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 to UTF-16.</li
31e70 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
31e80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
31e90 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 UTF-16 text and
31ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31eb0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 bytes() or.**
31ec0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
31ed0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
31ee0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
31ef0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
31f00 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
31f10 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 F-8.</li>.** </u
31f20 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 l>.**.** ^Conver
31f30 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
31f40 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
31f50 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
31f60 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
31f70 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
31f80 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
31f90 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
31fa0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
31fb0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
31fc0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
31fd0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 ior pointer refe
31fe0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 rences will have
31ff0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 been modified.
32000 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 Other kinds.**
32010 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 of conversion ar
32020 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 e done in place
32030 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 when it is possi
32040 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d ble, but sometim
32050 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e es they.** are n
32060 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 ot possible and
32070 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 in those cases p
32080 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 rior pointers ar
32090 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
320a0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 *.** The safest
320b0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 and easiest to r
320c0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 emember policy i
320d0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 s to invoke thes
320e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e e routines.** in
320f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
32100 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a owing ways:.**.*
32110 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 * <ul>.** <li>s
32120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32130 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 xt() followed by
32140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32150 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
32160 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
32170 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f umn_blob() follo
32180 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
32190 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
321a0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
321b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
321c0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
321d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
321e0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 tes16()</li>.**
321f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f </ul>.**.** In o
32200 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 ther words, you
32210 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 should call sqli
32220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
32230 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f ),.** sqlite3_co
32240 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 lumn_blob(), or
32250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32260 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f ext16() first to
32270 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c force the resul
32280 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 t.** into the de
32290 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 sired format, th
322a0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 en invoke sqlite
322b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
322c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
322d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
322e0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 to find the size
322f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 of the result.
32300 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c Do not mix call
32310 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
32320 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
32330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32340 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c blob() with call
32350 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
32360 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
32370 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 , and do not mix
32380 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
32390 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
323a0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 ).** with calls
323b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
323c0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a n_bytes()..**.**
323d0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 ^The pointers r
323e0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
323f0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
32400 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
32410 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
32420 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
32430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
32440 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
32450 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
32460 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
32470 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 ] is called. ^T
32480 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
32490 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
324a0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
324b0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
324c0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
324d0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
324e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
324f0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
32500 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
32510 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
32520 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
32530 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
32540 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ree()]..**.** ^(
32550 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
32560 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
32570 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 urs during the e
32580 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 valuation of any
32590 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 .** of these rou
325a0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 tines, a default
325b0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
325c0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
325d0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 value.** is eit
325e0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 her the integer
325f0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 0, the floating
32600 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 point number 0.0
32610 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 , or a NULL.** p
32620 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 ointer. Subsequ
32630 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
32640 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
32650 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
32660 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 [SQLITE_NOMEM].)
32670 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ^.*/.SQLITE_API
32680 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
32690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
326a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
326b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
326c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
326d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
326e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
326f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
32700 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
32710 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
32720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
32730 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
32740 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 PI double sqlite
32750 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 3_column_double(
32760 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
32770 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
32780 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
32790 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 _column_int(sqli
327a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
327b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
327c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
327d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
327e0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
327f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
32800 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 LITE_API const u
32810 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
32820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32830 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
32840 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
32850 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
32860 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
32870 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
32880 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
32890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
328a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
328b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 _type(sqlite3_st
328c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
328d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
328e0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 e3_value *sqlite
328f0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 3_column_value(s
32900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
32910 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t iCol);../*.**
32920 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f CAPI3REF: Destro
32930 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 y A Prepared Sta
32940 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
32950 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32960 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
32970 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
32980 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
32990 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
329a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
329b0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
329c0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
329d0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 ent encountered
329e0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 no errors.** or
329f0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
32a00 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 is never been e
32a10 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 valuated, then s
32a20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
32a30 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c ) returns.** SQL
32a40 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 ITE_OK. ^If the
32a50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
32a60 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 luation of state
32a70 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 ment S failed, t
32a80 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 hen.** sqlite3_f
32a90 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 inalize(S) retur
32aa0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ns the appropria
32ab0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
32ac0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
32ad0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
32ae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32af0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 finalize(S) rout
32b00 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
32b10 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
32b20 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 uring.** the lif
32b30 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 e cycle of [prep
32b40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
32b50 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 S:.** before sta
32b60 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 tement S is ever
32b70 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 evaluated, afte
32b80 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 r.** one or more
32b90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
32ba0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 e3_reset()], or
32bb0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a after any call.*
32bc0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 * to [sqlite3_st
32bd0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 ep()] regardless
32be0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
32bf0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ot the statement
32c00 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 has.** complete
32c10 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a d execution..**.
32c20 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c ** ^Invoking sql
32c30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
32c40 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 on a NULL pointe
32c50 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 r is a harmless
32c60 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 no-op..**.** The
32c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
32c80 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 t finalize every
32c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
32ca0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 ment] in order t
32cb0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 o avoid.** resou
32cc0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 rce leaks. It i
32cd0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 s a grievous err
32ce0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
32cf0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f cation to try to
32d00 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 use.** a prepar
32d10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ed statement aft
32d20 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
32d30 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 inalized. Any u
32d40 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 se of a prepared
32d50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 .** statement af
32d60 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
32d70 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 finalized can re
32d80 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
32d90 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 d and.** undesir
32da0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 able behavior su
32db0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 ch as segfaults
32dc0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 and heap corrupt
32dd0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
32de0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 PI int sqlite3_f
32df0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
32e00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
32e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
32e20 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
32e30 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
32e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
32e50 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 e3_reset() funct
32e60 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
32e70 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 reset a [prepar
32e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
32e90 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 object back to
32ea0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
32eb0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 e, ready to be r
32ec0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e e-executed..** ^
32ed0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e Any SQL statemen
32ee0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 t variables that
32ef0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e had values boun
32f00 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a d to them using.
32f10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
32f20 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 bind_blob | sqli
32f30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 te3_bind_*() API
32f40 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 ] retain their v
32f50 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 alues..** Use [s
32f60 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e qlite3_clear_bin
32f70 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 dings()] to rese
32f80 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a t the bindings..
32f90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
32fa0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
32fb0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 terface resets t
32fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
32fd0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 tement] S.** bac
32fe0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 k to the beginni
32ff0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 ng of its progra
33000 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 m..**.** ^If the
33010 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
33020 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
33030 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a ep(S)] for the.*
33040 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
33050 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 ement] S returne
33060 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f d [SQLITE_ROW] o
33070 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c r [SQLITE_DONE],
33080 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 .** or if [sqlit
33090 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 e3_step(S)] has
330a0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 never before bee
330b0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a n called on S,.*
330c0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f * then [sqlite3_
330d0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
330e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a s [SQLITE_OK]..*
330f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 *.** ^If the mos
33100 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
33110 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
33120 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 )] for the.** [p
33130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33140 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 t] S indicated a
33150 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a n error, then.**
33160 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
33170 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 S)] returns an a
33180 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
33190 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e r code]..**.** ^
331a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
331b0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
331c0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
331d0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f the values.** o
331e0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 f any [sqlite3_b
331f0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 ind_blob|binding
33200 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 s] on the [prepa
33210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
33220 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
33230 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 int sqlite3_rese
33240 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
33250 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
33260 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
33270 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
33280 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
33290 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
332a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
332b0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
332c0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
332d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
332e0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
332f0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
33300 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
33310 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ons}.**.** ^Thes
33320 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c e functions (col
33330 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 lectively known
33340 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 as "function cre
33350 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 ation routines")
33360 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 .** are used to
33370 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e add SQL function
33380 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 s or aggregates
33390 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 or to redefine t
333a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f he behavior.** o
333b0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 f existing SQL f
333c0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 unctions or aggr
333d0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c egates. The onl
333e0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 y differences be
333f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 tween.** these r
33400 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 outines are the
33410 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 text encoding ex
33420 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 pected for.** th
33430 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
33440 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 er (the name of
33450 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 the function bei
33460 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 ng created).** a
33470 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 nd the presence
33480 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 or absence of a
33490 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
334a0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ack for.** the a
334b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
334c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
334d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
334e0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 ter is the [data
334f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
33500 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 to which the SQ
33510 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 L.** function is
33520 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e to be added. ^
33530 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f If an applicatio
33540 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e n uses more than
33550 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a one database.**
33560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e connection then
33570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33580 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
33590 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 ns must be added
335a0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 .** to each data
335b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
335c0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
335d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 * ^The second pa
335e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e rameter is the n
335f0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 ame of the SQL f
33600 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 unction to be cr
33610 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 eated or.** rede
33620 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e fined. ^The len
33630 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 gth of the name
33640 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 is limited to 25
33650 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 5 bytes in a UTF
33660 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 -8.** representa
33670 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 tion, exclusive
33680 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d of the zero-term
33690 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 inator. ^Note t
336a0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 hat the name.**
336b0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 length limit is
336c0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 in UTF-8 bytes,
336d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e not characters n
336e0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e or UTF-16 bytes.
336f0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d .** ^Any attem
33700 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
33710 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
33720 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
33730 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 ll result in [SQ
33740 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 LITE_MISUSE] bei
33750 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a ng returned..**.
33760 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 ** ^The third pa
33770 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a rameter (nArg).*
33780 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 * is the number
33790 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
337a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
337b0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
337c0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 te takes. ^If th
337d0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 is parameter is
337e0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c -1, then the SQL
337f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
33800 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 aggregate may ta
33810 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 ke any number of
33820 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 arguments betwe
33830 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d en 0 and the lim
33840 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 it.** set by [sq
33850 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 lite3_limit]([SQ
33860 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
33870 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 ION_ARG]). If t
33880 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
33890 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 meter is less th
338a0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 an -1 or greater
338b0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 than 127 then t
338c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a he behavior is.*
338d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
338e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 ** ^The fourth p
338f0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 arameter, eTextR
33900 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 ep, specifies wh
33910 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 at.** [SQLITE_UT
33920 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 F8 | text encodi
33930 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e ng] this SQL fun
33940 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f ction prefers fo
33950 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 r.** its paramet
33960 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 ers. Every SQL
33970 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
33980 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 ntation must be
33990 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 able to work.**
339a0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d with UTF-8, UTF-
339b0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 16le, or UTF-16b
339c0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 e. But some imp
339d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 lementations may
339e0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 be.** more effi
339f0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 cient with one e
33a00 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f ncoding than ano
33a10 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 ther. ^An appli
33a20 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e cation may.** in
33a30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 voke sqlite3_cre
33a40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f ate_function() o
33a50 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
33a60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 _function16() mu
33a70 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 ltiple.** times
33a80 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 with the same fu
33a90 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 nction but with
33aa0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 different values
33ab0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a of eTextRep..**
33ac0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
33ad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
33ae0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
33af0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
33b00 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
33b10 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
33b20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
33b30 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
33b40 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
33b50 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 n..** If there i
33b60 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 s only a single
33b70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
33b80 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 hich does not ca
33b90 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 re what text.**
33ba0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
33bb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 , then the fourt
33bc0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c h argument shoul
33bd0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 d be [SQLITE_ANY
33be0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 ]..**.** ^(The f
33bf0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 ifth parameter i
33c00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 s an arbitrary p
33c10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 ointer. The imp
33c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 lementation of t
33c30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 he.** function c
33c40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 an gain access t
33c50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 o this pointer u
33c60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 sing [sqlite3_us
33c70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a er_data()].)^.**
33c80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 .** ^The sixth,
33c90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 seventh and eigh
33ca0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 th parameters, x
33cb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 Func, xStep and
33cc0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 xFinal, are.** p
33cd0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e ointers to C-lan
33ce0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 guage functions
33cf0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
33d00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
33d10 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e or.** aggregate.
33d20 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 ^A scalar SQL f
33d30 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
33d40 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
33d50 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
33d60 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
33d70 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 ; NULL pointers
33d80 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 must be passed a
33d90 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
33da0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
33db0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 ters. ^An aggreg
33dc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
33dd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 requires an imp
33de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 lementation of x
33df0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
33e00 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e al and NULL poin
33e10 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 ter must be pass
33e20 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 ed for xFunc. ^T
33e30 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 o delete an exis
33e40 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 ting.** SQL func
33e50 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
33e60 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 e, pass NULL poi
33e70 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 nters for all th
33e80 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ree function.**
33e90 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a callbacks..**.**
33ea0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 ^(If the ninth
33eb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
33ec0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33ed0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 tion_v2() is not
33ee0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 NULL,.** then i
33ef0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 t is destructor
33f00 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
33f10 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
33f20 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 . .** The destru
33f30 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 ctor is invoked
33f40 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f when the functio
33f50 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 n is deleted, ei
33f60 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a ther by being.**
33f70 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 overloaded or w
33f80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
33f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
33fa0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 es.)^.** ^The de
33fb0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f structor is also
33fc0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 invoked if the
33fd0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
33fe0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
33ff0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a on_v2() fails..*
34000 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 * ^When the dest
34010 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
34020 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 of the tenth par
34030 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 ameter is invoke
34040 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 d, it.** is pass
34050 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 ed a single argu
34060 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
34070 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c copy of the appl
34080 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a ication data .**
34090 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 pointer which w
340a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 as the fifth par
340b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
340c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
340d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 n_v2()..**.** ^I
340e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
340f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
34100 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
34110 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
34120 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
34130 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
34140 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
34150 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
34160 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
34170 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
34180 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
34190 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 codings. ^SQLit
341a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 e will use.** th
341b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
341c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 that most close
341d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 ly matches the w
341e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a ay in which the.
341f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
34200 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e is used. ^A fun
34210 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
34220 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d tion with a non-
34230 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 negative.** nArg
34240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
34250 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 better match tha
34260 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 n a function imp
34270 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
34280 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e .** a negative n
34290 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f Arg. ^A functio
342a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 n where the pref
342b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
342c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 ing.** matches t
342d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f he database enco
342e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 ding is a better
342f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 .** match than a
34300 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
34310 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 the encoding is
34320 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 different. .**
34330 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
34340 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
34350 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 ifference is bet
34360 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 ween UTF16le and
34370 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 UTF16be.** is a
34380 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 closer match th
34390 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
343a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
343b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a difference is.*
343c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 * between UTF8 a
343d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 nd UTF16..**.**
343e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 ^Built-in functi
343f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c ons may be overl
34400 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 oaded by new app
34410 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34420 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a functions..**.*
34430 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f * ^An applicatio
34440 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
34450 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 on is permitted
34460 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a to call other.**
34470 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
34480 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 es. However, su
34490 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f ch calls must no
344a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 t.** close the d
344b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
344c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 on nor finalize
344d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 or reset the pre
344e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
344f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 nt in which the
34500 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
34510 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
34520 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
34530 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a reate_function(.
34540 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
34550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
34560 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
34570 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
34580 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
34590 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
345a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
345b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
345c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
345d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
345e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
345f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
34600 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
34610 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
34620 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 text*).);.SQLITE
34630 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
34640 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
34650 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
34660 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
34670 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
34680 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
34690 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
346a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
346b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
346c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
346d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
346e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
346f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34700 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
34710 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
34720 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
34730 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 _context*).);.SQ
34740 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
34750 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
34760 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 tion_v2(. sqlit
34770 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
34780 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e char *zFunctionN
34790 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
347a0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
347b0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
347c0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
347d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
347e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
347f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
34800 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
34810 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
34820 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
34830 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
34840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c lite3_context*),
34850 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f . void(*xDestro
34860 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a y)(void*).);../*
34870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 .** CAPI3REF: Te
34880 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a xt Encodings.**.
34890 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
348a0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 t define integer
348b0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 codes that repr
348c0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 esent the variou
348d0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 s.** text encodi
348e0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 ngs supported by
348f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 SQLite..*/.#def
34900 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 ine SQLITE_UTF8
34910 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
34920 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
34930 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 LE 2.#def
34940 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
34950 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 BE 3.#def
34960 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
34970 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 4 /
34980 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 * Use native byt
34990 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 e order */.#defi
349a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 ne SQLITE_ANY
349b0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 5 /*
349c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
349d0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f function only */
349e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
349f0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
34a00 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
34a10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
34a20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
34a30 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 API3REF: Depreca
34a40 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ted Functions.**
34a50 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a DEPRECATED.**.*
34a60 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
34a70 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 s are [deprecate
34a80 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f d]. In order to
34a90 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
34aa0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
34ab0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
34ac0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 code, these func
34ad0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a tions continue .
34ae0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ** to be support
34af0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 ed. However, ne
34b00 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 w applications s
34b10 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 hould avoid.** t
34b20 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 he use of these
34b30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 functions. To h
34b40 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 elp encourage pe
34b50 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a ople to avoid.**
34b60 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e using these fun
34b70 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e ctions, we are n
34b80 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c ot going to tell
34b90 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 you what they d
34ba0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
34bb0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
34bc0 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 ATED.SQLITE_API
34bd0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
34be0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 D int sqlite3_ag
34bf0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
34c00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
34c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
34c20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
34c30 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 t sqlite3_expire
34c40 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 d(sqlite3_stmt*)
34c50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
34c60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
34c70 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
34c80 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
34c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
34ca0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
34cb0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
34cc0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
34cd0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f ite3_global_reco
34ce0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ver(void);.SQLIT
34cf0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
34d00 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c RECATED void sql
34d10 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
34d20 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nup(void);.SQLIT
34d30 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
34d40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
34d50 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
34d60 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 (void(*)(void*,s
34d70 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 qlite3_int64,int
34d80 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f ),void*,sqlite3_
34d90 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a int64);.#endif..
34da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34db0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 Obtaining SQL Fu
34dc0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 nction Parameter
34dd0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Values.**.** Th
34de0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
34df0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
34e00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
34e10 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
34e20 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
34e30 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
34e40 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
34e50 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
34e60 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
34e70 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
34e80 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 e..**.** The xFu
34e90 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
34ea0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
34eb0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
34ec0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
34ed0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
34ee0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
34ef0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
34f00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
34f10 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
34f20 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
34f30 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
34f40 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
34f50 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 egates..** The 3
34f60 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
34f70 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
34f80 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
34f90 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
34fa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
34fb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
34fc0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
34fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
34fe0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
34ff0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
35000 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
35010 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
35020 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
35030 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
35040 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
35050 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
35060 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
35070 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
35080 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
35090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
350a0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
350b0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
350c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
350d0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
350e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
350f0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
35100 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
35110 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 havior..**.** ^T
35120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
35130 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
35140 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
35150 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
35160 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
35170 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 pt that these r
35180 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
35190 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
351a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
351b0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
351c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
351d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
351e0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
351f0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
35200 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
35210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
35220 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
35230 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
35240 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
35250 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
35260 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
35270 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
35280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
35290 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
352a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
352b0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
352c0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
352d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
352e0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
352f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
35300 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
35310 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
35320 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
35330 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
35340 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
35350 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
35360 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
35370 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
35380 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
35390 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
353a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
353b0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
353c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
353d0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
353e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
353f0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
35400 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
35410 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
35420 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
35430 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
35440 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
35450 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
35460 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
35470 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
35480 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
35490 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
354a0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
354b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
354c0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
354d0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
354e0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
354f0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
35500 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
35510 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
35520 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
35530 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
35540 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
35550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
35560 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
35570 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
35580 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
35590 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
355a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
355b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
355c0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
355d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
355e0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
355f0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
35600 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
35610 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
35620 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
35630 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
35640 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
35650 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
35660 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
35670 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
35680 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
35690 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
356a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
356b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
356c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 value_blob(sqlit
356d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
356e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
356f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
35700 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
35710 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
35720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
35730 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c es16(sqlite3_val
35740 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
35750 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f double sqlite3_
35760 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
35770 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
35780 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
35790 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 ite3_value_int(s
357a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
357b0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
357c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
357d0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c _value_int64(sql
357e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
357f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 LITE_API const u
35800 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
35810 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
35820 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
35830 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
35840 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
35850 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 _value_text16(sq
35860 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
35870 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
35880 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
35890 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c lue_text16le(sql
358a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
358b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
358c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
358d0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
358e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
358f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
35900 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 te3_value_type(s
35910 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
35920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
35930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
35940 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 eric_type(sqlite
35950 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 3_value*);../*.*
35960 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
35970 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e in Aggregate Fun
35980 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a ction Context.**
35990 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 .** Implementati
359a0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 ons of aggregate
359b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
359c0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 se this.** routi
359d0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d ne to allocate m
359e0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e emory for storin
359f0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a g their state..*
35a00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
35a10 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 time the sqlite3
35a20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
35a30 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
35a40 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f is called .** fo
35a50 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
35a60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
35a70 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c n, SQLite.** all
35a80 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f ocates N of memo
35a90 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
35aa0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
35ab0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
35ac0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 r.** to the new
35ad0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f memory. ^On seco
35ae0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
35af0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
35b00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
35b10 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
35b20 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
35b30 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
35b40 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ce,.** the same
35b50 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
35b60 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 ed. Sqlite3_agg
35b70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
35b80 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 is normally.**
35b90 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
35ba0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 each invocation
35bb0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c of the xStep cal
35bc0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f lback and then o
35bd0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 ne.** last time
35be0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 when the xFinal
35bf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
35c00 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 ked. ^(When no
35c10 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e rows match.** an
35c20 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
35c30 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 , the xStep() ca
35c40 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 llback of the ag
35c50 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
35c60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
35c70 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c on is never call
35c80 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 ed and xFinal()
35c90 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c is called exactl
35ca0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 y once..** In th
35cb0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 ose cases, sqlit
35cc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
35cd0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 text() might be
35ce0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a called for the.*
35cf0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f * first time fro
35d00 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 m within xFinal(
35d10 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ).)^.**.** ^The
35d20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35d30 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
35d40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
35d50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
35d60 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 N is.** less th
35d70 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
35d80 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f ero or if a memo
35d90 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f ry allocate erro
35da0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 r occurs..**.**
35db0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 ^(The amount of
35dc0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 space allocated
35dd0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 by sqlite3_aggre
35de0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e gate_context(C,N
35df0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e ) is.** determin
35e00 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 ed by the N para
35e10 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 meter on first s
35e20 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 uccessful call.
35e30 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a Changing the.**
35e40 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 value of N in s
35e50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
35e60 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
35e70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 ate_context() wi
35e80 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 thin.** the same
35e90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
35ea0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c ion instance wil
35eb0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 l not resize the
35ec0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
35ed0 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ation.)^.**.** ^
35ee0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 SQLite automatic
35ef0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d ally frees the m
35f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 emory allocated
35f10 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 by .** sqlite3_a
35f20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
35f30 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 () when the aggr
35f40 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 egate query conc
35f50 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ludes..**.** The
35f60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
35f70 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 must be a copy
35f80 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
35f90 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c e3_context | SQL
35fa0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 function contex
35fb0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 t] that is the f
35fc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a irst parameter.*
35fd0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f * to the xStep o
35fe0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 r xFinal callbac
35ff0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 k routine that i
36000 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 mplements the ag
36010 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 gregate.** funct
36020 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
36030 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
36040 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
36050 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
36060 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
36070 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
36080 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
36090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
360a0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 d *sqlite3_aggre
360b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
360c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
360d0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
360e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
360f0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
36100 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ions.**.** ^The
36110 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
36120 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
36130 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
36140 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
36150 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
36160 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
36170 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
36180 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
36190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
361a0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
361b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
361c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
361d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
361e0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
361f0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
36200 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
36210 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
36220 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
36230 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
36240 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
36250 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
36260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36270 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
36280 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
36290 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
362a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 te3_user_data(sq
362b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
362c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
362d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
362e0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 ction For Functi
362f0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ons.**.** ^The s
36300 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
36310 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 b_handle() inter
36320 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
36330 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
36340 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 inter to the [da
36350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36360 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 n] (the 1st para
36370 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 meter).** of the
36380 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36390 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
363a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
363b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
363c0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 ] routines that
363d0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 originally.** re
363e0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 gistered the app
363f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
36400 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 function..*/.SQ
36410 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 LITE_API sqlite3
36420 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 *sqlite3_contex
36430 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 t_db_handle(sqli
36440 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
36450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36460 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
36470 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 ry Data.**.** Th
36480 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 e following two
36490 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
364a0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 used by scalar
364b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f SQL functions to
364c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 .** associate me
364d0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 tadata with argu
364e0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 ment values. If
364f0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 the same value i
36500 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d s passed to.** m
36510 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 ultiple invocati
36520 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
36530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 SQL function dur
36540 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 ing query execut
36550 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f ion, under.** so
36560 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 me circumstances
36570 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 the associated
36580 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 metadata may be
36590 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 preserved. This
365a0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 may.** be used,
365b0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 for example, to
365c0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 add a regular-ex
365d0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e pression matchin
365e0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 g scalar.** func
365f0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c tion. The compil
36600 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ed version of th
36610 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
36620 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 sion is stored a
36630 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 s.** metadata as
36640 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
36650 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 e SQL value pass
36660 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 ed as the regula
36670 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 r expression.**
36680 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f pattern. The co
36690 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
366a0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
366b0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
366c0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
366d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
366e0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 unction so that
366f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 the original pat
36700 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 tern string.** d
36710 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
36720 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e be recompiled on
36730 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e each invocation
36740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36750 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
36760 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
36770 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
36780 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a o the metadata.*
36790 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 * associated by
367a0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
367b0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 auxdata() functi
367c0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 on with the Nth
367d0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 argument.** valu
367e0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 e to the applica
367f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
36800 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 ction. ^If no me
36810 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 tadata has been
36820 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 ever.** been set
36830 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 for the Nth arg
36840 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e ument of the fun
36850 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 ction, or if the
36860 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
36870 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d * function param
36880 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 eter has changed
36890 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d since the meta-
368a0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a data was set,.**
368b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 then sqlite3_ge
368c0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75 t_auxdata() retu
368d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
368e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
368f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
36900 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 ta() interface s
36910 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 aves the metadat
36920 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 a.** pointed to
36930 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d by its 3rd param
36940 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 eter as the meta
36950 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 data for the N-t
36960 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 h.** argument of
36970 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36980 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36990 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a n. Subsequent.*
369a0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
369b0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
369c0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 might return th
369d0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 is data, if it h
369e0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 as.** not been d
369f0 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 estroyed..** ^If
36a00 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c it is not NULL,
36a10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
36a20 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
36a30 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 or.** function g
36a40 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 iven by the 4th
36a50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
36a60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
36a70 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 () on.** the met
36a80 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 adata when the c
36a90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
36aa0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
36ab0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 changes.** or wh
36ac0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
36ad0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 ment completes,
36ae0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 whichever comes
36af0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c first..**.** SQL
36b00 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 ite is free to c
36b10 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 all the destruct
36b20 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 or and drop meta
36b30 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 data on any.** p
36b40 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
36b50 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
36b60 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 time. ^The only
36b70 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 guarantee is th
36b80 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 at.** the destru
36b90 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c ctor will be cal
36ba0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d led before the m
36bb0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 etadata is dropp
36bc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 ed..**.** ^(In p
36bd0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 ractice, metadat
36be0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 a is preserved b
36bf0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 etween function
36c00 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 calls for.** exp
36c10 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 ressions that ar
36c20 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f e constant at co
36c30 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 mpile time. This
36c40 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 includes litera
36c50 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 l.** values and
36c60 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a [parameters].)^.
36c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
36c80 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
36c90 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
36ca0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
36cb0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
36cc0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
36cd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36ce0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 void *sqlite3_ge
36cf0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
36d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
36d10 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 N);.SQLITE_API v
36d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f oid sqlite3_set_
36d30 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
36d40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c context*, int N,
36d50 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 void*, void (*)
36d60 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a (void*));.../*.*
36d70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 * CAPI3REF: Cons
36d80 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 tants Defining S
36d90 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f pecial Destructo
36da0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a r Behavior.**.**
36db0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
36dc0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
36dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
36de0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
36df0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
36e00 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
36e10 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
36e20 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
36e30 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 . ^If the destr
36e40 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e uctor.** argumen
36e50 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 t is SQLITE_STAT
36e60 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 IC, it means tha
36e70 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f t the content po
36e80 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e inter is constan
36e90 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 t.** and will ne
36ea0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 ver change. It
36eb0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
36ec0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 be destroyed.
36ed0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 ^The.** SQLITE_T
36ee0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d RANSIENT value m
36ef0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
36f00 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c ntent will likel
36f10 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 y change in.** t
36f20 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 he near future a
36f30 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 nd that SQLite s
36f40 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f hould make its o
36f50 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
36f60 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e of.** the conten
36f70 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 t before returni
36f80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 ng..**.** The ty
36f90 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 pedef is necessa
36fa0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e ry to work aroun
36fb0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 d problems in ce
36fc0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d rtain.** C++ com
36fd0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 pilers. See tic
36fe0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 ket #2191..*/.ty
36ff0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c pedef void (*sql
37000 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
37010 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 type)(void*);.#d
37020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 efine SQLITE_STA
37030 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 TIC ((sqlit
37040 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
37050 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 pe)0).#define SQ
37060 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 LITE_TRANSIENT
37070 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
37080 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a uctor_type)-1)..
37090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
370a0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 Setting The Resu
370b0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e lt Of An SQL Fun
370c0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ction.**.** Thes
370d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 e routines are u
370e0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 sed by the xFunc
370f0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 or xFinal callb
37100 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 acks that.** imp
37110 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 lement SQL funct
37120 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
37130 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 tes. See.** [sq
37140 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
37150 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
37160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
37170 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f ction16()].** fo
37180 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
37190 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
371a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
371b0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c work very much l
371c0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 ike the [paramet
371d0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 er binding] fami
371e0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f ly of.** functio
371f0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 ns used to bind
37200 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 values to host p
37210 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 arameters in pre
37220 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
37230 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 ..** Refer to th
37240 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 e [SQL parameter
37250 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
37260 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 for additional i
37270 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
37280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
37290 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 esult_blob() int
372a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
372b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 result from.** a
372c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
372d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
372e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 o be the BLOB wh
372f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 ose content is p
37300 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 ointed.** to by
37310 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
37320 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 eter and which i
37330 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 s N bytes long w
37340 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a here N is the.**
37350 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
37360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37370 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f ite3_result_zero
37380 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 blob() interface
37390 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 s set the result
373a0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
373b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
373c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
373d0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 BLOB containing
373e0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 all zero.** byte
373f0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e s and N bytes in
37400 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 size, where N i
37410 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
37420 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
37430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37440 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
37450 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 le() interface s
37460 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 ets the result f
37470 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 rom.** an applic
37480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
37490 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 nction to be a f
374a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
374b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a lue specified.**
374c0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 by its 2nd argu
374d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
374e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
374f0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
37500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37510 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 16() functions.*
37520 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c * cause the impl
37530 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 emented SQL func
37540 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e tion to throw an
37550 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e exception..** ^
37560 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
37570 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 string pointed t
37580 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 o by the.** 2nd
37590 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
375a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
375b0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 r() or sqlite3_r
375c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a esult_error16().
375d0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f ** as the text o
375e0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 f an error messa
375f0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 ge. ^SQLite int
37600 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f erprets the erro
37610 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 r.** message str
37620 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ing from sqlite3
37630 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
37640 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 as UTF-8. ^SQLit
37650 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 e.** interprets
37660 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 the string from
37670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37680 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d rror16() as UTF-
37690 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 16 in native.**
376a0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 byte order. ^If
376b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
376c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
376d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a result_error().*
376e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
376f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 ult_error16() is
37700 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 negative then S
37710 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 QLite takes as t
37720 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 he error.** mess
37730 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 age all text up
37740 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 through the firs
37750 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 t zero character
37760 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 ..** ^If the thi
37770 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
37780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37790 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c rror() or.** sql
377a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
377b0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 r16() is non-neg
377c0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
377d0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e e takes that man
377e0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 y.** bytes (not
377f0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d characters) from
37800 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
37810 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 er as the error
37820 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 message..** ^The
37830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37840 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
37850 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
37860 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 16().** routines
37870 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 make a private
37880 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f copy of the erro
37890 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 r message text b
378a0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 efore.** they re
378b0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 turn. Hence, th
378c0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 e calling functi
378d0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 on can deallocat
378e0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 e or.** modify t
378f0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 he text after th
37900 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 ey return withou
37910 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 t harm..** ^The
37920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
37930 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 rror_code() func
37940 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 tion changes the
37950 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 error code.** r
37960 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 eturned by SQLit
37970 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 e as a result of
37980 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 an error in a f
37990 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 unction. ^By de
379a0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 fault,.** the er
379b0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 ror code is SQLI
379c0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 TE_ERROR. ^A su
379d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
379e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
379f0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 error().** or sq
37a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37a10 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 or16() resets th
37a20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 e error code to
37a30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a SQLITE_ERROR..**
37a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
37a50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f _result_error_to
37a60 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 obig() interface
37a70 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
37a80 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 o throw an.** er
37a90 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ror indicating t
37aa0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 hat a string or
37ab0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 BLOB is too long
37ac0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a to represent..*
37ad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
37ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 3_result_error_n
37af0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 omem() interface
37b00 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
37b10 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 o throw an.** er
37b20 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ror indicating t
37b30 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c hat a memory all
37b40 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a ocation failed..
37b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
37b60 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 e3_result_int()
37b70 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
37b80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
37b90 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
37ba0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
37bb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
37bc0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 32-bit signed i
37bd0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
37be0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
37bf0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
37c00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37c10 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 t_int64() interf
37c20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
37c30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
37c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
37c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
37c60 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 to be the 64-bi
37c70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
37c80 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
37c90 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
37ca0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
37cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
37cc0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 ull() interface
37cd0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
37ce0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
37cf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37d00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
37d10 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
37d20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
37d30 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
37d40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37d50 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 (),.** sqlite3_r
37d60 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 esult_text16le()
37d70 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 , and sqlite3_re
37d80 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 sult_text16be()
37d90 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 interfaces.** se
37da0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c t the return val
37db0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ue of the applic
37dc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
37dd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 nction to be.**
37de0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 a text string wh
37df0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 ich is represent
37e00 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 ed as UTF-8, UTF
37e10 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
37e20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 order,.** UTF-16
37e30 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 little endian,
37e40 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e or UTF-16 big en
37e50 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 dian, respective
37e60 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 ly..** ^SQLite t
37e70 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 akes the text re
37e80 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 sult from the ap
37e90 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a plication from.*
37ea0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 * the 2nd parame
37eb0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ter of the sqlit
37ec0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
37ed0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e interfaces..** ^
37ee0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
37ef0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
37f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
37f10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
37f20 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
37f30 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 SQLite takes re
37f40 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 sult text from t
37f50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
37f60 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 .** through the
37f70 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
37f80 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 cter..** ^If the
37f90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
37fa0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
37fb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
37fc0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d faces.** is non-
37fd0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 negative, then a
37fe0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f s many bytes (no
37ff0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 t characters) of
38000 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 the text.** poi
38010 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 nted to by the 2
38020 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 nd parameter are
38030 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 taken as the ap
38040 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
38050 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 d.** function re
38060 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 sult. If the 3r
38070 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e d parameter is n
38080 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
38090 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 n it.** must be
380a0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 the byte offset
380b0 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 into the string
380c0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 where the NUL te
380d0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a rminator would.*
380e0 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 * appear if the
380f0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c string where NUL
38100 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 terminated. If
38110 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 any NUL charact
38120 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ers occur.** in
38130 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 the string at a
38140 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 byte offset that
38150 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 is less than th
38160 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 e value of the 3
38170 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c rd.** parameter,
38180 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
38190 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 ing string will
381a0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 contain embedded
381b0 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a NULs and the.**
381c0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
381d0 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 ssions operating
381e0 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 on strings with
381f0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
38200 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
38210 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
38220 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
38230 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
38240 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
38250 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
38260 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d t_blob is a non-
38270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
38280 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 en SQLite calls
38290 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e that.** function
382a0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 as the destruct
382b0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f or on the text o
382c0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 r BLOB result wh
382d0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e en it has.** fin
382e0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
382f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
38300 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
38310 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
38320 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
38330 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a terfaces or to.*
38340 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
38350 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
38360 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
38370 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 LITE_STATIC, the
38380 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 n SQLite.** assu
38390 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 mes that the tex
383a0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 t or BLOB result
383b0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 is in constant
383c0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
383d0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 ot.** copy the c
383e0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 ontent of the pa
383f0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c rameter nor call
38400 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e a destructor on
38410 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 the content.**
38420 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 when it has fini
38430 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 shed using that
38440 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 result..** ^If t
38450 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
38460 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
38470 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 result_text* int
38480 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 erfaces.** or sq
38490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
384a0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c b is the special
384b0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 constant SQLITE
384c0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 _TRANSIENT.** th
384d0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 en SQLite makes
384e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 a copy of the re
384f0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 sult into space
38500 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a obtained from.**
38510 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
38520 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 alloc()] before
38530 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
38540 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
38550 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
38560 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
38570 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
38580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
38590 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
385a0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a o be a copy the.
385b0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
385c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
385d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 bject specified
385e0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
385f0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 eter. ^The.** s
38600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
38610 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 lue() interface
38620 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
38630 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
38640 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 ue].** so that t
38650 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
38660 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 e] specified in
38670 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 the parameter ma
38680 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 y change or.** b
38690 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 e deallocated af
386a0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 ter sqlite3_resu
386b0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 lt_value() retur
386c0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e ns without harm.
386d0 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 .** ^A [protecte
386e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
386f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 object may alwa
38700 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 ys be used where
38710 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
38720 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
38730 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 e] object is req
38740 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 uired, so either
38750 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c .** kind of [sql
38760 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
38770 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 ct can be used w
38780 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 ith this interfa
38790 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ce..**.** If the
387a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
387b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77