0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 35 2e 20 20 ersion 3.7.15.
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 the individual
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 ation.** unit.
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 .** possible if
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 ly. Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 ion unit..**.**
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f pile SQLite. To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 , you need this
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 lite3.h" header
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 rary. (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 d within.** the
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 e. Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 de files may be
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 want a wrapper
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 ource code. In
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 **.** May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 evil..** May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 thers..** May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 y, never taking
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 upport on POSIX
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 t. If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 * Ticket #2739:
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 t appear before
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c ncludes. Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 ode must be the
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 ITE_DISABLE_LFS
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 d line. This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 achine (ex: Red
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 want your code
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c . If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 option, LFS is
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 enable. But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 does not exist
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 't work. Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 r Mac OS X. LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 ne _LARGE_FILE
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 1.# ifndef
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 S.# define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 eader output by
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 NFIG_H.#include
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 eLimit.h in the
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 BLOB in bytes.
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 LITE_MAX_LENGTH
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 ber of.**.**
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c able.** * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 .** * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 in a view.**
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 * Terms in the
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 t.** * Terms
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 atement.** *
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 .** * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 The hard upper
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 676. Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 lized database,
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e n any table. An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 d if.** that is
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 the case, there
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aving more than
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 alues in any of
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 gth of a single
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 used to be the
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 g this value to
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f . That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 nger true. It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 etime you might
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 ** A value of 0
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 But that is no
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 longer true. Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 rm. A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 o large. In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 rms. Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 codes in a VDBE
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 program..** Not
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 ndif../*.** The
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 * table and for
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 . The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 CHE_SIZE 2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 SIZE 500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ode..*/.#ifndef
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 TOCHECKPOINT 10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 ber of attached
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 databases. This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 0.** and 62. T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 n 62 is because
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 track attached
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 imum value of a
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 size. The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 r bound on this
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 value is 65536.
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 imposed by the
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 nger permitted,
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 is technically
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 ocess operating
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 s crashes, then
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 mit will not be
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 tion..*/.#ifdef
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 .** The default
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 ULT_PAGE_SIZE.#
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 FAULT_PAGE_SIZE
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 ort),.** SQLite
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 ger value. This
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 constant is the
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 max_page_count
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 pragma..** This
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 cro..*/.#ifndef
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 c */.#endif../*
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 ers to integers
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 and.** integers
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 to pointers. Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 have developed
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 y to do this is
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 rs.** that vary
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d : The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 construct. But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 MSVC chokes on
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ys depending on
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 ) /* This case
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 should work for
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 GCC */.# define
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f R(X) ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 X) ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 __GNUC__)
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a _PTR(X) ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 _PTR_TO_INT(X)
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 STDINT_H) /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 se this case if
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 TR(X) ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 intptr_t)(X)).#
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 R_TO_INT(X) ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 ).#else
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 /* Generates a
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 _INT_TO_PTR(X)
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e _TO_INT(X) ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 e. 1 means the
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 ety. 2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 iple.** threads
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 threads try to
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 ion at the same
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 EADSAFE.#else.#
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61 f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20 fe overwrite is
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 on by default.
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65 But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74 d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45 he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f 0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41 f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64 FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57 efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41 The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61 ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20 ned as either 0
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65 or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72 r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76 MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75 ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20 lt or not. This
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20 value can.** be
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75 overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20 ntime using the
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46 fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66 * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65 acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69 o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74 tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 o use..**.**
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f ALLOC /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73 / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20 tem malloc().**
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 _MALLOC
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52 * SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 O_MALLOC
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75 // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44 SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20 EBUG
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20 // Debugging
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65 version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20 On Windows, if
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45 _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65 macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73 d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65 ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32 l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62 native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63 system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74 ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20 e to be called.
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74 If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72 will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65 rical note: The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65 re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69 veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20 * pared it down
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68 to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65 one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59 en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 OC) \. + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 ALLOC) \. + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 _MALLOC) \. + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64 ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65 but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53 is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33 LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22 ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 M_MALLOC) \. +
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57 defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 IN32_MALLOC) \.
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c . + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30 ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31 _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79 t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20 to keep the.**
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 sizes of memory
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65 w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20 LIMIT).# define
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65 FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58 eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66 OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20 ollows in order
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63 to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74 n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53 ems. But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53 .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75 OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72 ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65 Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20 told,.** so it
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65 is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72 673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20 XOPEN_SOURCE is
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72 poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73 nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f tems. So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61 id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69 t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65 s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77 needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69 e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20 ng a threadsafe
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23 build. Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2681..**.** See
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34 also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65 DARWIN__) && !de
3c10: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29 fined(__APPLE__)
3c20: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41 && SQLITE_THREA
3c30: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20 DSAFE.# define
3c40: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30 _XOPEN_SOURCE 50
3c50: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20 0 /* Needed to
3c60: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72 enable pthread r
3c70: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 ecursive mutexes
3c80: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a */.#endif../*.*
3c90: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72 * The TCL header
3ca0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65 s are only neede
3cb0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 d when compiling
3cc0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67 the TCL binding
3cd0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 s..*/.#if define
3ce0: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c d(SQLITE_TCL) ||
3cf0: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a defined(TCLSH).
3d00: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68 # include <tcl.h
3d10: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 >.#endif../*.**
3d20: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54 NDEBUG and SQLIT
3d30: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f E_DEBUG are oppo
3d40: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c sites. It shoul
3d50: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 d always be true
3d60: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64 that.** defined
3d70: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e (NDEBUG)==!defin
3d80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 ed(SQLITE_DEBUG)
3d90: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f . If this is no
3da0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65 t currently true
3db0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75 ,.** make it tru
3dc0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72 e by defining or
3dd0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42 undefining NDEB
3de0: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e UG..**.** Settin
3df0: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74 g NDEBUG makes t
3e00: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20 he code smaller
3e10: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62 and run faster b
3e20: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a y disabling the.
3e30: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74 ** number assert
3e40: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e () statements in
3e50: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77 the code. So w
3e60: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75 e want the defau
3e70: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 lt action.** to
3e80: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f be for NDEBUG to
3e90: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42 be set and NDEB
3ea0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e UG to be undefin
3eb0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54 ed only if SQLIT
3ec0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65 E_DEBUG.** is se
3ed0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20 t. Thus NDEBUG
3ee0: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69 becomes an opt-i
3ef0: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e n rather than an
3f00: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74 opt-out.** feat
3f10: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 ure..*/.#if !def
3f20: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20 ined(NDEBUG) &&
3f30: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f !defined(SQLITE_
3f40: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65 DEBUG) .# define
3f50: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66 NDEBUG 1.#endif
3f60: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45 .#if defined(NDE
3f70: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28 BUG) && defined(
3f80: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20 SQLITE_DEBUG).#
3f90: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e undef NDEBUG.#en
3fa0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 dif../*.** The t
3fb0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 estcase() macro
3fc0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69 is used to aid i
3fd0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 n coverage testi
3fe0: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f ng. When .** do
3ff0: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 ing coverage tes
4000: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74 ting, the condit
4010: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61 ion inside the a
4020: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 rgument to.** te
4030: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65 stcase() must be
4040: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20 evaluated both
4050: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69 true and false i
4060: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65 n order to.** ge
4070: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f t full branch co
4080: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73 verage. The tes
4090: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 tcase() macro is
40a0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20 inserted.** to
40b0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71 help ensure adeq
40c0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61 uate test covera
40d0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65 ge in places whe
40e0: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e re simple.** con
40f0: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 dition/decision
4100: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64 coverage is inad
4110: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61 equate. For exa
4120: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29 mple, testcase()
4130: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 .** can be used
4140: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75 to make sure bou
4150: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65 ndary values are
4160: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a tested. For.**
4170: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20 bitmask tests,
4180: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62 testcase() can b
4190: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73 e used to make s
41a0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20 ure each bit.**
41b0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61 is significant a
41c0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74 nd used at least
41d0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63 once. On switc
41e0: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 h statements.**
41f0: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63 where multiple c
4200: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73 ases go to the s
4210: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 ame block of cod
4220: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a e, testcase().**
4230: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74 can insure that
4240: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65 all cases are e
4250: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a valuated..**.*/.
4260: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f #ifdef SQLITE_CO
4270: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49 VERAGE_TEST.SQLI
4280: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69 TE_PRIVATE voi
4290: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67 d sqlite3Coverag
42a0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65 e(int);.# define
42b0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66 testcase(X) if
42c0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f ( X ){ sqlite3Co
42d0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 verage(__LINE__)
42e0: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 ; }.#else.# defi
42f0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23 ne testcase(X).#
4300: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
4310: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 TESTONLY macro
4320: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f is used to enclo
4330: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c se variable decl
4340: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f arations or.** o
4350: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64 ther bits of cod
4360: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65 e that are neede
4370: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65 d to support the
4380: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 arguments.** wi
4390: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20 thin testcase()
43a0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63 and assert() mac
43b0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 ros..*/.#if !def
43c0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20 ined(NDEBUG) ||
43d0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43 defined(SQLITE_C
43e0: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20 OVERAGE_TEST).#
43f0: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 define TESTONLY(
4400: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 X) X.#else.# de
4410: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 fine TESTONLY(X)
4420: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 .#endif../*.** S
4430: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64 ometimes we need
4440: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 a small amount
4450: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20 of code such as
4460: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69 a variable initi
4470: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 alization.** to
4480: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65 setup for a late
4490: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 r assert() state
44a0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74 ment. We do not
44b0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20 want this code
44c0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65 to.** appear whe
44d0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69 n assert() is di
44e0: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c sabled. The fol
44f0: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20 lowing macro is
4500: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65 therefore.** use
4510: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61 d to contain tha
4520: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54 t setup code. T
4530: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d he "VVA" acronym
4540: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 stands for.** "
4550: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61 Verification, Va
4560: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63 lidation, and Ac
4570: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49 creditation". I
4580: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
4590: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69 he.** code withi
45a0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c n VVA_ONLY() wil
45b0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e l only run durin
45c0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70 g verification p
45d0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 rocesses..*/.#if
45e0: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65 ndef NDEBUG.# de
45f0: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 fine VVA_ONLY(X)
4600: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 X.#else.# defi
4610: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 ne VVA_ONLY(X).#
4620: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 endif../*.** The
4630: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 ALWAYS and NEVE
4640: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e R macros surroun
4650: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73 d boolean expres
4660: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20 sions which .**
4670: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
4680: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f always be true o
4690: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74 r false, respect
46a0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20 ively. Such.**
46b0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c expressions coul
46c0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f d be omitted fro
46d0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c m the code compl
46e0: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79 etely. But they
46f0: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64 .** are included
4700: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20 in a few cases
4710: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61 in order to enha
4720: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e nce the resilien
4730: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 ce.** of SQLite
4740: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65 to unexpected be
4750: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 havior - to make
4760: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d the code "self-
4770: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 healing".** or "
4780: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20 ductile" rather
4790: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74 than being "brit
47a0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e tle" and crashin
47b0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a g at the first.*
47c0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e * hint of unplan
47d0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
47e0: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
47f0: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e ds, ALWAYS and N
4800: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66 EVER are added f
4810: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64 or defensive cod
4820: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f e..**.** When do
4830: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73 ing coverage tes
4840: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20 ting ALWAYS and
4850: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63 NEVER are hard-c
4860: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72 oded to.** be tr
4870: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20 ue and false so
4880: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68 that the unreach
4890: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73 able code then s
48a0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e pecify will.** n
48b0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73 ot be counted as
48c0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a untested code..
48d0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 */.#if defined(S
48e0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54 QLITE_COVERAGE_T
48f0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c EST).# define AL
4900: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29 WAYS(X) (1)
4910: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28 .# define NEVER(
4920: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c X) (0).#el
4930: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 if !defined(NDEB
4940: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 UG).# define ALW
4950: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29 AYS(X) ((X)
4960: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29 ?1:(assert(0),0)
4970: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 ).# define NEVER
4980: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28 (X) ((X)?(
4990: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a assert(0),1):0).
49a0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41 #else.# define A
49b0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58 LWAYS(X) (X
49c0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 ).# define NEVER
49d0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65 (X) (X).#e
49e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 ndif../*.** Retu
49f0: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 rn true (non-zer
4a00: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 o) if the input
4a10: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61 is a integer tha
4a20: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a t is too large.*
4a30: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62 * to fit in 32-b
4a40: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f its. This macro
4a50: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20 is used inside
4a60: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63 of various testc
4a70: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 ase().** macros
4a80: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77 to verify that w
4a90: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51 e have tested SQ
4aa0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66 Lite for large-f
4ab0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a ile support..*/.
4ac0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49 #define IS_BIG_I
4ad0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69 NT(X) (((X)&~(i
4ae0: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d 64)0xffffffff)!=
4af0: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 0)../*.** The ma
4b00: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69 cro unlikely() i
4b10: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75 s a hint that su
4b20: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61 rrounds a boolea
4b30: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
4b40: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20 that is usually
4b50: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69 false. Macro li
4b60: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73 kely() surrounds
4b70: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78 .** a boolean ex
4b80: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73 pression that is
4b90: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20 usually true.
4ba0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a GCC is able to.*
4bb0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74 * use these hint
4bc0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65 s to generate be
4bd0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74 tter code, somet
4be0: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 imes..*/.#if def
4bf0: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 ined(__GNUC__) &
4c00: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b & 0.# define lik
4c10: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c ely(X) __buil
4c20: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31 tin_expect((X),1
4c30: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b ).# define unlik
4c40: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69 ely(X) __builti
4c50: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a n_expect((X),0).
4c60: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c #else.# define l
4c70: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58 ikely(X) !!(X
4c80: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b ).# define unlik
4c90: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65 ely(X) !!(X).#e
4ca0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ndif../*********
4cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 ***** Include sq
4cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d lite3.h in the m
4cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 iddle of sqliteI
4ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
4cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ****/./*********
4d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 ***** Begin file
4d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a sqlite3.h *****
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 ****/./*.** 2001
4d50: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a September 15.**
4d60: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64 .** The author d
4d70: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 isclaims copyrig
4d80: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63 ht to this sourc
4d90: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 e code. In plac
4da0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 e of.** a legal
4db0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20 notice, here is
4dc0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a a blessing:.**.*
4dd0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 * May you do
4de0: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 good and not evi
4df0: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 l..** May you
4e00: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 find forgivenes
4e10: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 s for yourself a
4e20: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72 nd forgive other
4e30: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 s..** May you
4e40: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e share freely, n
4e50: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 ever taking more
4e60: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a than you give..
4e70: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **.*************
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 ************.**
4ec0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65 This header file
4ed0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
4ee0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20 erface that the
4ef0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a SQLite library.*
4f00: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c * presents to cl
4f10: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20 ient programs.
4f20: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c If a C-function,
4f30: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61 structure, data
4f40: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 type,.** or cons
4f50: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20 tant definition
4f60: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 does not appear
4f70: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68 in this file, th
4f80: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 en it is.** not
4f90: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20 a published API
4fa0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75 of SQLite, is su
4fb0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
4fc0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 without.** notic
4fd0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f e, and should no
4fe0: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20 t be referenced
4ff0: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74 by programs that
5000: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a use SQLite..**.
5010: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64 ** Some of the d
5020: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20 efinitions that
5030: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65 are in this file
5040: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a are marked as.*
5050: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22 * "experimental"
5060: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 . Experimental
5070: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
5080: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 ormally new.** f
5090: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79 eatures recently
50a0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65 added to SQLite
50b0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74 . We do not ant
50c0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a icipate changes.
50d0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74 ** to experiment
50e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75 al interfaces bu
50f0: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69 t reserve the ri
5100: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f ght to make mino
5110: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20 r changes.** if
5120: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
5130: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
5140: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
5150: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
5160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
5170: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
5180: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
5190: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
51a0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
51b0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
51c0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
51d0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
51e0: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
51f0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
5200: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
5210: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
5220: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
5230: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
5240: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
5250: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
5260: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
5270: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
5280: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
5290: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
52a0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
52b0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
52c0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
52d0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
52e0: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
52f0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
5300: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
5310: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 cess..*/.#ifndef
5320: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65 _SQLITE3_H_.#de
5330: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f fine _SQLITE3_H_
5340: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
5350: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
5360: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
5370: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
5380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
5390: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
53a0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
53b0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 C++..*/.#if 0.e
53c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
53d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 if.../*.** Add t
53e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 he ability to ov
53f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a erride 'extern'.
5400: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
5410: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e E_EXTERN.# defin
5420: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 e SQLITE_EXTERN
5430: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 extern.#endif..#
5440: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 ifndef SQLITE_AP
5450: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 I.# define SQLIT
5460: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f E_API.#endif.../
5470: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 *.** These no-op
5480: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 macros are used
5490: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 in front of int
54a0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 erfaces to mark
54b0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 those.** interfa
54c0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 ces as either de
54d0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 precated or expe
54e0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 rimental. New a
54f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
5500: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 hould not use de
5510: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 precated interfa
5520: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 ces - they are s
5530: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 upport for backw
5540: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
5550: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 ility only. App
5560: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 lication writers
5570: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 should be aware
5580: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d that.** experim
5590: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
55a0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 are subject to
55b0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 change in point
55c0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
55d0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 These macros use
55e0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 d to resolve to
55f0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 various kinds of
5600: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
5610: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 that.** would ge
5620: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d nerate warning m
5630: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 essages when the
5640: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 y were used. Bu
5650: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c t that.** compil
5660: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 er magic ended u
5670: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 p generating suc
5680: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 h a flurry of bu
5690: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 g reports.** tha
56a0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 t we have taken
56b0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 it all out and g
56c0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e one back to usin
56d0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 g simple.** noop
56e0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 macros..*/.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 ine SQLITE_DEPRE
5700: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 CATED.#define SQ
5710: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
5720: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 L../*.** Ensure
5730: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 these symbols we
5740: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 re not defined b
5750: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 y some previous
5760: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a header file..*/.
5770: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 #ifdef SQLITE_VE
5780: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 RSION.# undef SQ
5790: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e LITE_VERSION.#en
57a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
57b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
57c0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
57d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
57e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
57f0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
5800: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
5810: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a ion Numbers.**.*
5820: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f * ^(The [SQLITE_
5830: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 VERSION] C prepr
5840: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e ocessor macro in
5850: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 the sqlite3.h h
5860: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 eader.** evaluat
5870: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c es to a string l
5880: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 iteral that is t
5890: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f he SQLite versio
58a0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d n in the.** form
58b0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 at "X.Y.Z" where
58c0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 X is the major
58d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 version number (
58e0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 always 3 for.**
58f0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 SQLite3) and Y i
5900: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 s the minor vers
5910: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a ion number and Z
5920: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 is the release
5930: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 number.)^.** ^(T
5940: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
5950: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 ON_NUMBER] C pre
5960: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
5970: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 resolves to an i
5980: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 nteger.** with t
5990: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 he value (X*1000
59a0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 000 + Y*1000 + Z
59b0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e ) where X, Y, an
59c0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 d Z are the same
59d0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 .** numbers used
59e0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 in [SQLITE_VERS
59f0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 ION].)^.** The S
5a00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
5a10: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 MBER for any giv
5a20: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 en release of SQ
5a30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a Lite will also.*
5a40: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e * be larger than
5a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f the release fro
5a60: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 m which it is de
5a70: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 rived. Either Y
5a80: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 will.** be held
5a90: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 constant and Z
5aa0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e will be incremen
5ab0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 ted or else Y wi
5ac0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
5ad0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 d.** and Z will
5ae0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f be reset to zero
5af0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 ..**.** Since ve
5b00: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 rsion 3.6.18, SQ
5b10: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 Lite source code
5b20: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 has been stored
5b30: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 in the.** <a hr
5b40: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 ef="http://www.f
5b50: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e ossil-scm.org/">
5b60: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 Fossil configura
5b70: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a tion management.
5b80: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 ** system</a>.
5b90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 ^The SQLITE_SOUR
5ba0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c CE_ID macro eval
5bb0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 uates to.** a st
5bc0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 ring which ident
5bd0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c ifies a particul
5be0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 ar check-in of S
5bf0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 QLite.** within
5c00: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f its configuratio
5c10: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 n management sys
5c20: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 tem. ^The SQLIT
5c30: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 E_SOURCE_ID.** s
5c40: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 tring contains t
5c50: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 he date and time
5c60: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e of the check-in
5c70: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 (UTC) and an SH
5c80: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 A1.** hash of th
5c90: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 e entire source
5ca0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tree..**.** See
5cb0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c also: [sqlite3_l
5cc0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a ibversion()],.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
5ce0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 sion_number()],
5cf0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 [sqlite3_sourcei
5d00: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
5d10: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
5d20: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
5d30: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 d()]..*/.#define
5d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 SQLITE_VERSION
5d50: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 35 22 0a "3.7.15".
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
5d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 ERSION_NUMBER 30
5d80: 30 37 30 31 35 0a 23 64 65 66 69 6e 65 20 53 51 07015.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 LITE_SOURCE_ID
5da0: 20 20 20 20 22 32 30 31 32 2d 31 30 2d 31 35 20 "2012-10-15
5db0: 32 30 3a 32 38 3a 32 32 20 32 63 33 61 66 36 35 20:28:22 2c3af65
5dc0: 37 66 65 65 36 31 35 33 38 34 32 64 36 36 30 61 7fee6153842d660a
5dd0: 36 63 65 32 39 61 61 37 64 37 39 31 65 62 64 33 6ce29aa7d791ebd3
5de0: 38 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8"../*.** CAPI3R
5df0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
5e00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
5e10: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 bers.** KEYWORDS
5e20: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f : sqlite3_versio
5e30: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 n, sqlite3_sourc
5e40: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 eid.**.** These
5e50: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 interfaces provi
5e60: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f de the same info
5e70: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b rmation as the [
5e80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c SQLITE_VERSION],
5e90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
5ea0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 ION_NUMBER], and
5eb0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
5ec0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
5ed0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 or macros.** but
5ee0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 are associated
5ef0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
5f00: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
5f10: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 header file. ^(
5f20: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 Cautious.** prog
5f30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e rammers might in
5f40: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 clude assert() s
5f50: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
5f60: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
5f70: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 o.** verify that
5f80: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
5f90: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 by these interf
5fa0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d aces match the m
5fb0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 acros in.** the
5fc0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 header, and thus
5fd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 insure that the
5fe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a application is.
5ff0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
6000: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 matching librar
6010: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c y and header fil
6020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b es..**.** <block
6030: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 quote><pre>.** a
6040: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c ssert( sqlite3_l
6050: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
6060: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 ()==SQLITE_VERSI
6070: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 ON_NUMBER );.**
6080: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
6090: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
60a0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f ),SQLITE_SOURCE_
60b0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 ID)==0 );.** ass
60c0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 ert( strcmp(sqli
60d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
60e0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 ,SQLITE_VERSION)
60f0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ==0 );.** </pre>
6100: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
6110: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
6120: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
6130: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
6140: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
6150: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f f [SQLITE_VERSIO
6160: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 N].** macro. ^T
6170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
6180: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
6190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
61a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 er to the.** to
61b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
61c0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
61d0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 stant. The sqli
61e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
61f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
6200: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 provided for use
6210: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 in DLLs since D
6220: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 LL users usually
6230: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 do not have.**
6240: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
6250: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
6260: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c s within the DLL
6270: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
6280: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
6290: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 mber() function
62a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
62b0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b er equal to.** [
62c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
62d0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 UMBER]. ^The sq
62e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
62f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
6300: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
6310: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
6320: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 tant whose value
6330: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
6340: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
6350: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
6360: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e processor macro.
6370: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
6380: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e [sqlite_version
6390: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f ()] and [sqlite_
63a0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f source_id()]..*/
63b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
63c0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 t char sqlite3_v
63d0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 ersion[] = SQLIT
63e0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 E_VERSION;.SQLIT
63f0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
6400: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 *sqlite3_libver
6410: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 sion(void);.SQLI
6420: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
6430: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
6440: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 eid(void);.SQLIT
6450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
6460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
6470: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ber(void);../*.*
6480: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
6490: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d Time Library Com
64a0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 pilation Options
64b0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a Diagnostics.**.
64c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
64d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
64e0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 ed() function re
64f0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a turns 0 or 1 .**
6500: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 indicating whet
6510: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 her the specifie
6520: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 d option was def
6530: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 ined at .** comp
6540: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 ile time. ^The
6550: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d SQLITE_ prefix m
6560: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 ay be omitted fr
6570: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f om the .** optio
6580: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f n name passed to
6590: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
65a0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 option_used().
65b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
65c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
65d0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e n_get() function
65e0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e allows iteratin
65f0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 g.** over the li
6600: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 st of options th
6610: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 at were defined
6620: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 at compile time
6630: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 by.** returning
6640: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 the N-th compile
6650: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 time option str
6660: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f ing. ^If N is o
6670: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 ut of range,.**
6680: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
6690: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 ption_get() retu
66a0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
66b0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 er. ^The SQLITE
66c0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 _ .** prefix is
66d0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 omitted from any
66e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
66f0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d by .** sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
6710: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 et()..**.** ^Sup
6720: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 port for the dia
6730: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e gnostic function
6740: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c s sqlite3_compil
6750: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a eoption_used().*
6760: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
6770: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
6780: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 ) may be omitted
6790: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 by specifying t
67a0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
67b0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f MIT_COMPILEOPTIO
67c0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 N_DIAGS] option
67d0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
67e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
67f0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b SQL functions [
6800: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 sqlite_compileop
6810: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 tion_used()] and
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 .** [sqlite_comp
6830: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d ileoption_get()]
6840: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c and the [compil
6850: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 e_options pragma
6860: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 ]..*/.#ifndef SQ
6870: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
6880: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 EOPTION_DIAGS.SQ
6890: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
68a0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
68b0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 on_used(const ch
68c0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 ar *zOptName);.S
68d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
68e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
68f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
6900: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6920: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
6930: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
6940: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
6950: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
6960: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
6970: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
6980: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
6990: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
69a0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
69b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
69c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
69d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
69e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
69f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
6a00: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
6a10: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
6a20: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
6a30: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
6a40: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
6a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
6a60: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
6a70: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
6a80: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
6a90: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
6aa0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
6ab0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
6ac0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
6ad0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
6ae0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
6af0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
6b00: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
6b10: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
6b20: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
6b30: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
6b40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
6b50: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
6b60: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
6b70: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
6b80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
6b90: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
6ba0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
6bb0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
6bc0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
6bd0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
6be0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
6bf0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
6c00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
6c10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
6c20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
6c30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
6c40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
6c50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
6c60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
6c70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
6c80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
6c90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
6ca0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
6cb0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
6cc0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
6cd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
6ce0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
6cf0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
6d00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
6d10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
6d20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
6d30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
6d40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
6d50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
6d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
6d70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
6d80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
6d90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
6da0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
6db0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
6dc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
6dd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
6de0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
6df0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
6e00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
6e10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
6e20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
6e30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
6e40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
6e50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
6e60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
6e70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
6e80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
6e90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
6ea0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
6eb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
6ec0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
6ed0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
6ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
6ef0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
6f00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
6f10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
6f20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
6f30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
6f40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
6f50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
6f60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
6f70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
6f80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
6f90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
6fa0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
6fb0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
6fc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
6fd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
6fe0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
6ff0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
7000: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
7010: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
7020: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
7030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
7040: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
7050: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
7060: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
7070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
7080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7090: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
70a0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
70b0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
70c0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
70d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
70e0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
70f0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
7100: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
7110: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
7120: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
7130: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
7140: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
7150: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
7160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
7170: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
7180: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
7190: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
71a0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
71b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
71c0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 se()].** and [sq
71d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
71e0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 ] are its destru
71f0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 ctors. There ar
7200: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 e many other.**
7210: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 interfaces (such
7220: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f as.** [sqlite3_
7230: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
7240: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
7250: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a unction()], and.
7260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
7270: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e _timeout()] to n
7280: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 ame but three) t
7290: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 hat are methods
72a0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 on an.** sqlite3
72b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 object..*/.type
72c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
72d0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a e3 sqlite3;../*.
72e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
72f0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
7300: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 s.** KEYWORDS: s
7310: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
7320: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
7330: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
7340: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
7350: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
7360: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
7370: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
7380: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
7390: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
73a0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
73b0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
73c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
73d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
73e0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
73f0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
7400: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
7410: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
7420: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
7430: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
7440: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
7450: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
7460: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
7470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
7480: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 64 and sqlite_in
7490: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 t64 types can st
74a0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ore integer valu
74b0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 es.** between -9
74c0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
74d0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 08 and +92233720
74e0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 36854775807 incl
74f0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 usive. ^The.**
7500: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 sqlite3_uint64 a
7510: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
7520: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
7530: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
7540: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e .** between 0 an
7550: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 d +1844674407370
7560: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 9551615 inclusiv
7570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
7580: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 ITE_INT64_TYPE.
7590: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
75a0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
75b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
75c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 ef unsigned SQLI
75d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
75e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
75f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f if defined(_MSC_
7600: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 VER) || defined(
7610: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 __BORLANDC__).
7620: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 typedef __int64
7630: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
7640: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
7650: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
7660: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 uint64;.#else.
7670: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e typedef long lon
7680: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 g int sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
76a0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 signed long long
76b0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 int sqlite_uint
76c0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 64;.#endif.typed
76d0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 ef sqlite_int64
76e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 sqlite3_int64;.t
76f0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 ypedef sqlite_ui
7700: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e nt64 sqlite3_uin
7710: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 t64;../*.** If c
7720: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 ompiling for a p
7730: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 rocessor that la
7740: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 cks floating poi
7750: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 nt support,.** s
7760: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 ubstitute intege
7770: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 r for floating-p
7780: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 oint..*/.#ifdef
7790: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 SQLITE_OMIT_FLOA
77a0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 TING_POINT.# def
77b0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 ine double sqlit
77c0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a e3_int64.#endif.
77d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
77e0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 Closing A Datab
77f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
7800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
7810: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 3_close() and sq
7820: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
7830: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
7840: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 structors.** for
7850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
7860: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 bject..** ^Calls
7870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to sqlite3_clos
7880: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
7890: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 close_v2() retur
78a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a n SQLITE_OK if.*
78b0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 * the [sqlite3]
78c0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 object is succes
78d0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 sfully destroyed
78e0: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 and all associa
78f0: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 ted.** resources
7900: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 are deallocated
7910: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
7920: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
7930: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 ion is associate
7940: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
7950: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 ed prepared.** s
7960: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 tatements or unf
7970: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
7980: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 backup objects t
7990: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 hen sqlite3_clos
79a0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 e().** will leav
79b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
79c0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 onnection open a
79d0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
79e0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 E_BUSY]..** ^If
79f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
7a00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
7a10: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 h unfinalized pr
7a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
7a30: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73 s.** and unfinis
7a40: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b hed sqlite3_back
7a50: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 ups, then the da
7a60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7a70: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 n becomes.** an
7a80: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 unusable "zombie
7a90: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 " which will aut
7aa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 omatically be de
7ab0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 allocated when t
7ac0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 he.** last prepa
7ad0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
7ae0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 finalized or th
7af0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 e last sqlite3_b
7b00: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 ackup is.** fini
7b10: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 shed. The sqlit
7b20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e e3_close_v2() in
7b30: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e terface is inten
7b40: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 ded for use with
7b50: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 .** host languag
7b60: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 es that are garb
7b70: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 age collected, a
7b80: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 nd where the ord
7b90: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 er in which.** d
7ba0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 estructors are c
7bb0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 alled is arbitra
7bc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ry..**.** Applic
7bd0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 ations should [s
7be0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
7bf0: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 | finalize] all
7c00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
7c10: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ents],.** [sqlit
7c20: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 e3_blob_close |
7c30: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 close] all [BLOB
7c40: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a handles], and .
7c50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b ** [sqlite3_back
7c60: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 up_finish | fini
7c70: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 sh] all [sqlite3
7c80: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
7c90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
7ca0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
7cb0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 ] object prior t
7cc0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 o attempting to
7cd0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 close the object
7ce0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 . ^If.** sqlite
7cf0: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 3_close() is cal
7d00: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
7d20: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
7d30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
7d40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
7d50: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
7d60: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
7d70: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
7d80: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
7d90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b eturns SQLITE_OK
7da0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63 but the dealloc
7db0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f ation.** of reso
7dc0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 urces is deferre
7dd0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 d until all [pre
7de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
7df0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 ], [BLOB handles
7e00: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 ],.** and [sqlit
7e10: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 e3_backup] objec
7e20: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 ts are also dest
7e30: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 royed..**.** ^If
7e40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 an [sqlite3] ob
7e50: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 ject is destroye
7e60: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 d while a transa
7e70: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a ction is open,.*
7e80: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f * the transactio
7e90: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c n is automatical
7ea0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
7eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 **.** The C para
7ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
7ed0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 3_close(C)] and
7ee0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 [sqlite3_close_v
7ef0: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 2(C)].** must be
7f00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a either a NULL.*
7f10: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 * pointer or an
7f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
7f30: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 pointer obtaine
7f40: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
7f50: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
7f60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
7f70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
7f80: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e pen_v2()], and n
7f90: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c ot previously cl
7fa0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e osed..** ^Callin
7fb0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 g sqlite3_close(
7fc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f ) or sqlite3_clo
7fd0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e se_v2() with a N
7fe0: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 ULL pointer.** a
7ff0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 rgument is a har
8000: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a mless no-op..*/.
8010: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
8020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
8030: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 ite3*);.SQLITE_A
8040: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
8050: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
8060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
8070: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
8080: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
8090: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
80a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
80b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
80c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
80d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
80e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
80f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
8100: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
8110: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
8120: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
8130: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
8140: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
8150: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
8160: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 erface.**.** The
8170: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8180: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 interface is a c
8190: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 onvenience wrapp
81a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 er around.** [sq
81b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
81c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
81d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
81e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c te3_finalize()],
81f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 .** that allows
8200: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
8210: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 o run multiple s
8220: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c tatements of SQL
8230: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 .** without havi
8240: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 ng to use a lot
8250: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a of C code. .**.*
8260: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
8270: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
8280: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 runs zero or mor
8290: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c e UTF-8 encoded,
82a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 .** semicolon-se
82b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 parate SQL state
82c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
82d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 o its 2nd argume
82e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f nt,.** in the co
82f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 ntext of the [da
8300: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
8310: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 n] passed in as
8320: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d its 1st.** argum
8330: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ent. ^If the ca
8340: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
8350: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d of the 3rd argum
8360: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ent to.** sqlite
8370: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
8380: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 NULL, then it is
8390: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 invoked for eac
83a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 h result row.**
83b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 coming out of th
83c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 e evaluated SQL
83d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 statements. ^Th
83e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 e 4th argument t
83f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
8400: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 c() is relayed t
8410: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 hrough to the 1s
8420: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 t argument of ea
8430: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ch.** callback i
8440: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 nvocation. ^If
8450: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 the callback poi
8460: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f nter to sqlite3_
8470: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c exec().** is NUL
8480: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 L, then no callb
8490: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f ack is ever invo
84a0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 ked and result r
84b0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 ows are.** ignor
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ed..**.** ^If an
84d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 error occurs wh
84e0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 ile evaluating t
84f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
8500: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a s passed into.**
8510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c sqlite3_exec(),
8520: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 then execution
8530: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 of the current s
8540: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 tatement stops a
8550: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 nd.** subsequent
8560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
8570: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 skipped. ^If th
8580: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
8590: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
85a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ).** is not NULL
85b0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 then any error
85c0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 message is writt
85d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
85e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
85f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
8600: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 )] and passed ba
8610: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ck through the 5
8620: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a th parameter..**
8630: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 To avoid memory
8640: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c leaks, the appl
8650: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 ication should i
8660: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
8670: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 ree()].** on err
8680: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
8690: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f gs returned thro
86a0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
86b0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 meter of.** of s
86c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 qlite3_exec() af
86d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 ter the error me
86e0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
86f0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
8700: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 ..** ^If the 5th
8710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
8720: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
8730: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 not NULL and no
8740: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c errors.** occur,
8750: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 then sqlite3_ex
8760: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f ec() sets the po
8770: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 inter in its 5th
8780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
8790: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 NULL before ret
87a0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 urning..**.** ^I
87b0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 f an sqlite3_exe
87c0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 c() callback ret
87d0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
87e0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
87f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
8800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 urns SQLITE_ABOR
8810: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 T without invoki
8820: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ng the callback
8830: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 again and.** wit
8840: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 hout running any
8850: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
8860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
8870: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d * ^The 2nd argum
8880: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
8890: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
88a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ck function is t
88b0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
88c0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
88d0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 esult. ^The 3rd
88e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
88f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
8900: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ** callback is a
8910: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
8920: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f ers to strings o
8930: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 btained as if fr
8940: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 om.** [sqlite3_c
8950: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f olumn_text()], o
8960: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 ne for each colu
8970: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d mn. ^If an elem
8980: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 ent of a.** resu
8990: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 lt row is NULL t
89a0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
89b0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 nding string poi
89c0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 nter for the.**
89d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
89e0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c allback is a NUL
89f0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
8a00: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
8a10: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f the.** sqlite3_
8a20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
8a30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
8a40: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
8a50: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a gs where each.**
8a60: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 entry represent
8a70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f s the name of co
8a80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 rresponding resu
8a90: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 lt column as obt
8aa0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 ained.** from [s
8ab0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
8ac0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 me()]..**.** ^If
8ad0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
8ae0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
8af0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 ec() is a NULL p
8b00: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 ointer, a pointe
8b10: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 r.** to an empty
8b20: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f string, or a po
8b30: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 inter that conta
8b40: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ins only whitesp
8b50: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 ace and/or .** S
8b60: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 QL comments, the
8b70: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 n no SQL stateme
8b80: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 nts are evaluate
8b90: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 d and the databa
8ba0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 se.** is not cha
8bb0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 nged..**.** Rest
8bc0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 rictions:.**.**
8bd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
8be0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8bf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 t insure that th
8c00: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
8c10: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
8c20: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 ).** is a v
8c30: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 alid and open [d
8c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
8c50: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 on]..** <li> The
8c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
8c70: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 t not close [dat
8c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
8c90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
8ca0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
8cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
8cc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
8cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
8ce0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
8cf0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
8d00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
8d10: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
8d20: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
8d30: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
8d40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
8d50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
8d60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
8d70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
8d80: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
8d90: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
8da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
8db0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
8de0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
8df0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
8e00: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
8e20: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
8e30: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
8e40: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
8e50: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
8e60: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
8e70: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
8e80: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
8eb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
8ec0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
8ed0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8ef0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
8f00: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
8f10: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
8f20: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
8f30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
8f40: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f SQLITE_OK {erro
8f50: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 r code} {error c
8f60: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 odes}.** KEYWORD
8f70: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d S: {result code}
8f80: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a {result codes}.
8f90: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
8fa0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
8fb0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
8fc0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
8fd0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
8fe0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
8ff0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 indicate succes
9000: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a s or failure..**
9010: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f .** New error co
9020: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 des may be added
9030: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
9040: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
9050: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
9060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
9070: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 D | extended res
9080: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b ult codes],.** [
9090: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f sqlite3_vtab_on_
90a0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c conflict()] [SQL
90b0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 ITE_ROLLBACK | r
90c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f esult codes]..*/
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
90e0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 OK 0
90f0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 /* Successful r
9100: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 esult */./* begi
9110: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 nning-of-error-c
9120: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 odes */.#define
9130: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 SQLITE_ERROR
9140: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 1 /* SQL e
9150: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 rror or missing
9160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
9180: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 NAL 2 /* I
9190: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 nternal logic er
91a0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f ror in SQLite */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
91c0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 PERM 3
91d0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 /* Access permi
91e0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ssion denied */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
9200: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 BORT 4
9210: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 /* Callback rout
9220: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e ine requested an
9230: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e abort */.#defin
9240: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 e SQLITE_BUSY
9250: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 5 /* The
9260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
9270: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 s locked */.#def
9280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
9290: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 D 6 /* A
92a0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 table in the da
92b0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 tabase is locked
92c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
92d0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 TE_NOMEM
92e0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 7 /* A malloc(
92f0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 ) failed */.#def
9300: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
9310: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 NLY 8 /* A
9320: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 ttempt to write
9330: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 a readonly datab
9340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
9350: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 QLITE_INTERRUPT
9360: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 9 /* Operat
9370: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 ion terminated b
9380: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 y sqlite3_interr
9390: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 upt()*/.#define
93a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 SQLITE_IOERR
93b0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 10 /* Some
93c0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f kind of disk I/O
93d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 error occurred
93e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
93f0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 E_CORRUPT 11
9400: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
9410: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 se disk image is
9420: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 malformed */.#d
9430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
9440: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a FOUND 12 /*
9450: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 Unknown opcode
9460: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f in sqlite3_file_
9470: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 control() */.#de
9480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c fine SQLITE_FULL
9490: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 13 /*
94a0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 Insertion failed
94b0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 because databas
94c0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 e is full */.#de
94d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
94e0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 OPEN 14 /*
94f0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 Unable to open t
9500: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
9520: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 TE_PROTOCOL 1
9530: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
9540: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 lock protocol er
9550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
9560: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 QLITE_EMPTY
9570: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 16 /* Databa
9580: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 se is empty */.#
9590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 define SQLITE_SC
95a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f HEMA 17 /
95b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 * The database s
95c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f chema changed */
95d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
95e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 TOOBIG 18
95f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c /* String or BL
9600: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 OB exceeds size
9610: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 limit */.#define
9620: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
9630: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 NT 19 /* Abor
9640: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 t due to constra
9650: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f int violation */
9660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9670: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 MISMATCH 20
9680: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 /* Data type mi
9690: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e smatch */.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 e SQLITE_MISUSE
96b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 21 /* Lib
96c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 rary used incorr
96d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ectly */.#define
96e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 SQLITE_NOLFS
96f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 22 /* Uses
9700: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 OS features not
9710: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f supported on ho
9720: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 st */.#define SQ
9730: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 LITE_AUTH
9740: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 23 /* Authori
9750: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f zation denied */
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9770: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 FORMAT 24
9780: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 /* Auxiliary da
9790: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 tabase format er
97a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
97b0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 QLITE_RANGE
97c0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 25 /* 2nd pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
97e0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 e3_bind out of r
97f0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ange */.#define
9800: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 SQLITE_NOTADB
9810: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 26 /* File
9820: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e opened that is n
9830: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 ot a database fi
9840: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
9850: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
9860: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
9870: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
9880: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
9890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
98a0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
98b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
98c0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
98d0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
98e0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
98f0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
9900: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
9910: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
9920: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
9930: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
9940: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
9950: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
9960: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
9970: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
9980: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9990: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
99a0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
99b0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
99c0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
99d0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
99e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
99f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
9a00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
9a10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
9a20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
9a30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
9a40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
9a50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
9a60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
9a70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
9a80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
9a90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
9aa0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
9ab0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
9ac0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
9ad0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
9ae0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
9af0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
9b00: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
9b10: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
9b20: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
9b30: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
9b40: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
9b50: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
9b60: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
9b70: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
9b80: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
9b90: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
9ba0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
9bb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9bc0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
9bd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
9be0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
9bf0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
9c00: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
9c10: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
9c20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
9c30: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
9c40: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
9c50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
9c60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
9c70: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
9c80: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
9c90: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
9ca0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
9cb0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
9cc0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
9cd0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
9ce0: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
9cf0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
9d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
9d10: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
9d20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
9d30: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
9d40: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
9d50: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
9d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9d70: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
9d80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9d90: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a IOERR | (1<<8)).
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
9db0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
9dc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
9dd0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9df0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
9e10: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
9e30: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
9e50: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
9e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
9e70: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
9e80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
9e90: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 R | (5<<8)).#def
9ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
9eb0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 _TRUNCATE
9ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
9ed0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
9ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
9ef0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 FSTAT
9f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
9f10: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
9f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
9f30: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 NLOCK
9f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
9f50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
9f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
9f70: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
9f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9f90: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
9fb0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 ETE (
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
9fd0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
9ff0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 CKED (
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a010: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 11<<8)).#define
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d SQLITE_IOERR_NOM
a030: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 EM (
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a050: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 12<<8)).#define
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
a070: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 ESS (
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a090: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 13<<8)).#define
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 SQLITE_IOERR_CHE
a0b0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 CKRESERVEDLOCK (
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a0d0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 14<<8)).#define
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 SQLITE_IOERR_LOC
a0f0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a110: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 15<<8)).#define
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f SQLITE_IOERR_CLO
a130: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 SE (
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a150: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 16<<8)).#define
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
a170: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 _CLOSE (
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a190: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 17<<8)).#define
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a1b0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 OPEN (
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a1d0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 18<<8)).#define
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a1f0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 SIZE (
a200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a210: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 19<<8)).#define
a220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a230: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 LOCK (
a240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a250: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 20<<8)).#define
a260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
a270: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 MAP (
a280: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a290: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 21<<8)).#define
a2a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 SQLITE_IOERR_SEE
a2b0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
a2c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
a2d0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 22<<8)).#define
a2e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
a2f0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
a300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
a310: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
a320: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
a330: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
a340: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
a350: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
a360: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
a370: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
a380: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
a390: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
a3a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
a3b0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
a3c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
a3d0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
a3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
a3f0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 TOPEN_FULLPATH
a400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
a410: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a TOPEN | (3<<8)).
a420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
a430: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 ORRUPT_VTAB
a440: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
a450: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 ORRUPT | (1<<8))
a460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a470: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
a480: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
a490: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
a4a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
a4b0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
a4c0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
a4d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
a4e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
a4f0: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 ITE_ABORT_ROLLBA
a500: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c CK (SQL
a510: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c ITE_ABORT | (2<<
a520: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8))../*.** CAPI3
a530: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
a540: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
a550: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
a560: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
a570: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
a580: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
a590: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
a5a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
a5b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
a5c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
a5d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
a5e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
a5f0: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 en] method..*/.#
a600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a610: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
a620: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 0x00000001
a630: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a640: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a660: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
a670: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 0x00000002
a680: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a690: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a6a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a6b0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
a6c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 0x00000004
a6d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a6e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a700: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
a710: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 0x00000008
a720: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a740: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
a750: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 0x00000010
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 41 55 54 4f 50 52 4f 58 59 20 20 20 20 EN_AUTOPROXY
a790: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 0x00000020
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 55 52 49 20 20 20 20 20 20 20 20 20 20 EN_URI
a7d0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 0x00000040
a7e0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a7f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a810: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 EN_MEMORY
a820: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 0x00000080
a830: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
a840: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
a850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a860: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
a870: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 0x00000100
a880: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
a890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
a8a0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
a8b0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 0x00000200
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 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
a8f0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 0x00000400
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
a930: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 0x00000800
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 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
a970: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 0x00001000
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 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
a9b0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 0x00002000
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 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
a9f0: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 L 0x00004000
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 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 EN_NOMUTEX
aa30: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 0x00008000
aa40: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
aa50: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
aa60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aa70: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 EN_FULLMUTEX
aa80: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 0x00010000
aa90: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
aaa0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
aab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
aac0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 EN_SHAREDCACHE
aad0: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 0x00020000
aae0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
aaf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
ab00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
ab10: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
ab20: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 0x00040000
ab30: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
ab40: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
ab50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
ab60: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 EN_WAL
ab70: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 0x00080000
ab80: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a /* VFS only */..
ab90: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 /* Reserved:
aba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
abb0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 0x00F00000
abc0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
abd0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 EF: Device Chara
abe0: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a cteristics.**.**
abf0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
ac00: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
ac10: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 od of the [sqlit
ac20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
ac30: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 * object returns
ac40: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
ac50: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 h is a vector of
ac60: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
ac70: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
ac80: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
ac90: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
aca0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
acb0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
acc0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
acd0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
ace0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
acf0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
ad00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
ad10: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
ad20: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
ad30: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
ad40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
ad50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
ad60: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
ad70: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
ad80: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
ad90: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
ada0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
adb0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
adc0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
add0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
ade0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
adf0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
ae00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
ae10: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
ae20: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
ae30: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
ae40: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
ae50: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
ae60: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
ae70: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
ae80: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
ae90: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
aea0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
aeb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
aec0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
aed0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
aee0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
aef0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
af00: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
af10: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
af20: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 * to xWrite().
af30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
af40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
af50: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 RITE property me
af60: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 ans that.** afte
af70: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 r reboot followi
af80: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f ng a crash or po
af90: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e wer loss, the on
afa0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a ly bytes in a.**
afb0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 file that were
afc0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 written at the a
afd0: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c pplication level
afe0: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e might have chan
aff0: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ged.** and that
b000: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 adjacent bytes,
b010: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 even bytes withi
b020: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f n the same secto
b030: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 r are.** guarant
b040: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e eed to be unchan
b050: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ged..*/.#define
b060: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
b070: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
b080: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
b090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
b0a0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
b0b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
b0c0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
b0d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
b0e0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
b0f0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
b100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
b110: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
b120: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
b130: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
b140: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
b150: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
b160: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
b170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
b180: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
b190: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
b1a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
b1b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
b1c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
b1d0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
b1e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
b1f0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
b200: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
b210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
b220: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
b230: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
b240: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
b250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
b260: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
b270: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
b280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
b290: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
b2a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
b2b0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
b2c0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
b2d0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
b2e0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
b2f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
b300: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
b310: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
b320: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
b330: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
b340: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 Levels.**.** SQ
b350: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 Lite uses one of
b360: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
b370: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
b380: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
b390: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
b3a0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
b3b0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
b3c0: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
b3d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
b3e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
b3f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
b400: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
b410: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
b420: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
b430: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
b440: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
b450: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
b460: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
b470: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
b480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
b490: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
b4a0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
b4b0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
b4c0: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a tion Type Flags.
b4d0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
b4e0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
b4f0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
b500: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
b510: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
b520: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
b530: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 ination of.** th
b540: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ese integer valu
b550: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 es as the second
b560: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
b570: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 When the SQLITE
b580: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 _SYNC_DATAONLY f
b590: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 lag is used, it
b5a0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a means that the.*
b5b0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e * sync operation
b5c0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 only needs to f
b5d0: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 lush data to mas
b5e0: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 s storage. Inod
b5f0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
b600: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 need not be flu
b610: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 shed. If the low
b620: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 er four bits of
b630: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 the flag.** equa
b640: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f l SQLITE_SYNC_NO
b650: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 RMAL, that means
b660: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 to use normal f
b670: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 sync() semantics
b680: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 ..** If the lowe
b690: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 r four bits equa
b6a0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 l SQLITE_SYNC_FU
b6b0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a LL, that means.*
b6c0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 * to use Mac OS
b6d0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
b6e0: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
b6f0: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f c()..**.** Do no
b700: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 t confuse the SQ
b710: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
b720: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
b730: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 _FULL flags.** w
b740: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 ith the [PRAGMA
b750: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 synchronous]=NOR
b760: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 MAL and [PRAGMA
b770: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c synchronous]=FUL
b780: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 L.** settings.
b790: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 The [synchronous
b7a0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 pragma] determi
b7b0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 nes when calls t
b7c0: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 o the.** xSync V
b7d0: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 FS method occur
b7e0: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 and applies unif
b7f0: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c ormly across all
b800: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 platforms..** T
b810: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
b820: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
b830: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
b840: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a determine how.*
b850: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 * energetic or r
b860: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 igorous or force
b870: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 ful the sync ope
b880: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a rations are and.
b890: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 ** only make a d
b8a0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 ifference on Mac
b8b0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 OSX for the def
b8c0: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 ault SQLite code
b8d0: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 ..** (Third-part
b8e0: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 y VFS implementa
b8f0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f tions might also
b900: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
b910: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e ction.** between
b920: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
b930: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
b940: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d YNC_FULL, but am
b950: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 ong the.** opera
b960: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 ting systems nat
b970: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 ively supported
b980: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 by SQLite, only
b990: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 Mac OSX.** cares
b9a0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 about the diffe
b9b0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 rence.).*/.#defi
b9c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e ne SQLITE_SYNC_N
b9d0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 ORMAL 0x0
b9e0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
b9f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 ITE_SYNC_FULL
ba00: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 0x00003.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
ba20: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 NC_DATAONLY
ba30: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 0x00010../*.**
ba40: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
ba50: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 erface Open File
ba60: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e Handle.**.** An
ba70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
ba80: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
ba90: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 s an open file i
baa0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 n the .** [sqlit
bab0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 e3_vfs | OS inte
bac0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 rface layer]. I
bad0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
bae0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d erface.** implem
baf0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a entations will.*
bb00: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 * want to subcla
bb10: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 ss this object b
bb20: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 y appending addi
bb30: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a tional fields.**
bb40: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 for their own u
bb50: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 se. The pMethod
bb60: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 s entry is a poi
bb70: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
bb80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
bb90: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
bba0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 efines methods f
bbb0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a or performing.**
bbc0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
bbd0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 on the open file
bbe0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
bbf0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
bc00: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 sqlite3_file;.s
bc10: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
bc20: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 le {. const str
bc30: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
bc40: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 ethods *pMethods
bc50: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f ; /* Methods fo
bc60: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a r an open file *
bc70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
bc80: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
bc90: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 ce File Virtual
bca0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a Methods Object.*
bcb0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 *.** Every file
bcc0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 opened by the [s
bcd0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
bce0: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 ] method populat
bcf0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 es an.** [sqlite
bd00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 3_file] object (
bd10: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c or, more commonl
bd20: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 y, a subclass of
bd30: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
bd40: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 _file] object) w
bd50: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
bd60: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
bd70: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 this object..**
bd80: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 This object defi
bd90: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 nes the methods
bda0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
bdb0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
bdc0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 ns.** against th
bdd0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 e open file repr
bde0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b esented by the [
bdf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
be00: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ject..**.** If t
be10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
be20: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 xOpen] method se
be30: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
be40: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
be50: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
be60: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
be70: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
be80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
be90: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
bea0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
beb0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 if the [sqlite3
bec0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f _vfs.xOpen] repo
bed0: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 rted that it fai
bee0: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c led. The.** onl
bef0: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 y way to prevent
bf00: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 a call to xClos
bf10: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 e following a fa
bf20: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 iled [sqlite3_vf
bf30: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 s.xOpen].** is f
bf40: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
bf50: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 vfs.xOpen] to se
bf60: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
bf70: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
bf80: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a ent.** to NULL..
bf90: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
bfa0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
bfb0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
bfc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
bfd0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
bfe0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
bff0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
c000: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
c010: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
c020: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
c030: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
c040: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
c050: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
c060: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
c070: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
c080: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
c090: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
c0a0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
c0b0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
c0c0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
c0d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
c0e0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
c0f0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
c100: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
c110: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
c120: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
c130: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
c140: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
c150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c160: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
c170: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c180: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
c190: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
c1a0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
c1b0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
c1c0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
c1d0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
c1e0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
c1f0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
c200: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
c210: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
c220: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
c230: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c240: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
c250: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
c260: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
c270: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
c280: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
c290: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
c2a0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
c2b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
c2c0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
c2d0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
c2e0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
c2f0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
c300: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
c310: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
c320: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
c330: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
c340: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
c350: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
c360: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
c370: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
c380: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
c390: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
c3a0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
c3b0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
c3c0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
c3d0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
c3e0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
c3f0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
c400: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
c410: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
c420: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
c430: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
c440: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
c450: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
c460: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
c470: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
c480: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
c490: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
c4a0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
c4b0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
c4c0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
c4d0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
c4e0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
c4f0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
c500: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
c510: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
c520: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
c530: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
c540: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
c550: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
c560: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
c570: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
c580: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
c590: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
c5a0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 wn use..** A [SQ
c5b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
c5c0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f TATE | list of o
c5d0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
c5e0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
c5f0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
c600: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
c610: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
c620: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
c630: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
c640: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
c650: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
c660: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
c670: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
c680: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
c690: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
c6a0: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
c6b0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
c6c0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
c6d0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
c6e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
c6f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
c700: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
c710: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
c720: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
c730: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
c740: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
c750: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
c760: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
c770: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
c780: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
c790: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
c7a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
c7b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
c7c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
c7d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
c7e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
c7f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
c800: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
c810: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
c820: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
c840: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
c850: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
c860: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c870: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
c880: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
c890: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
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 34 4b 5d 0a IOCAP_ATOMIC4K].
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 38 4b 5d 0a IOCAP_ATOMIC8K].
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 31 36 4b 5d IOCAP_ATOMIC16K]
c900: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c910: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
c920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
c930: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
c940: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
c950: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
c960: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
c970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
c980: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
c990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
c9a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
c9b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
c9c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
c9d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
c9e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
c9f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
ca00: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
ca10: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
ca20: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
ca30: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
ca40: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
ca50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
ca60: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
ca70: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
ca80: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
ca90: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
caa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
cab0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
cac0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
cad0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
cae0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
caf0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
cb00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
cb10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
cb20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
cb30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
cb40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
cb50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
cb60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
cb70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
cb80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
cb90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
cba0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
cbb0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
cbc0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
cbd0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
cbe0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
cbf0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
cc00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
cc10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
cc20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
cc30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
cc40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
cc50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
cc60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
cc70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
cc80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
cc90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
cca0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
ccb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
ccc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
ccd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
cce0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
ccf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
cd00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
cd10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
cd20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
cd30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
cd40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
cd50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
cd60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
cd70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
cd80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
cd90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
cda0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
cdb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
cdc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
cdd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
cde0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
cdf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
ce00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
ce10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
ce20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
ce30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
ce40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
ce50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
ce60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
ce70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
ce80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
ce90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
cea0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
ceb0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
cec0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
ced0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
cee0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
cef0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
cf00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
cf10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
cf20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
cf30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
cf40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
cf50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
cf60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
cf70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
cf80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
cf90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
cfa0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
cfb0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
cfc0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
cfd0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
cfe0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
cff0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
d000: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
d010: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
d020: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
d030: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
d040: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
d050: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
d060: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
d070: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
d080: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
d090: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
d0a0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
d0b0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
d0c0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
d0d0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
d0e0: 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 n 2 */. /* Addi
d0f0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d tional methods m
d100: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
d110: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a uture releases *
d120: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
d130: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 3REF: Standard F
d140: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f ile Control Opco
d150: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 des.**.** These
d160: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
d170: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
d180: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
d190: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
d1a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
d1b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
d1c0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
d1d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
d1e0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
d1f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 e..**.** The [SQ
d200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
d210: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
d220: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
d230: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
d240: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
d250: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
d260: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
d270: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
d280: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
d290: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
d2a0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
d2b0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
d2c0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
d2d0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
d2e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
d2f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
d300: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
d310: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
d320: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
d330: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
d340: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
d350: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
d360: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
d370: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
d380: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
d390: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 SQLITE_TEST.** i
d3a0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 s defined..** <u
d3b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 l>.** <li>[[SQLI
d3c0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
d3d0: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NT]].** The [SQL
d3e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
d3f0: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 INT] opcode is u
d400: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f sed by SQLite to
d410: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a give the VFS.**
d420: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 layer a hint of
d430: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 how large the d
d440: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
d450: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 l grow to be dur
d460: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 ing the.** curre
d470: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 nt transaction.
d480: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
d490: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 t guaranteed to
d4a0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 be accurate but
d4b0: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 it.** is often c
d4c0: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 lose. The under
d4d0: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 lying VFS might
d4e0: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c choose to preall
d4f0: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a ocate database.*
d500: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 * file space bas
d510: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 ed on this hint
d520: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 in order to help
d530: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 writes to the d
d540: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
d550: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a run faster..**.*
d560: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
d570: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
d580: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
d590: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
d5a0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
d5b0: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 d to request tha
d5c0: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 t the VFS.** ext
d5d0: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 ends and truncat
d5e0: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
d5f0: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f file in chunks o
d600: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 f a size specifi
d610: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 ed.** by the use
d620: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 r. The fourth ar
d630: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
d640: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
d650: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f )] should .** po
d660: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 int to an intege
d670: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e r (type int) con
d680: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 taining the new
d690: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 chunk-size to us
d6a0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d e.** for the nom
d6b0: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e inated database.
d6c0: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 Allocating data
d6d0: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 base file space
d6e0: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e in large.** chun
d6f0: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 ks (say 1MB at a
d700: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 time), may redu
d710: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 ce file-system f
d720: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 ragmentation and
d730: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 .** improve perf
d740: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 ormance on some
d750: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c systems..**.** <
d760: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
d770: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d L_FILE_POINTER]]
d780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
d790: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
d7a0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ER] opcode is us
d7b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 ed to obtain a p
d7c0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
d7d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
d7e0: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 object associate
d7f0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 d with a particu
d800: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
d810: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
d820: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d830: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f le_control()] do
d840: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a cumentation for.
d850: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
d860: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
d870: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d880: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
d890: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c ]].** ^(The [SQL
d8a0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
d8b0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 MITTED] opcode i
d8c0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 s generated inte
d8d0: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c rnally by.** SQL
d8e0: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 ite and sent to
d8f0: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 all VFSes in pla
d900: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 ce of a call to
d910: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
d920: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 .** when the dat
d930: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
d940: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e has [PRAGMA syn
d950: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f chronous] set to
d960: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 OFF.)^.** Some
d970: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
d980: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e s need this sign
d990: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f al in order to o
d9a0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 perate correctly
d9b0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 .** when [PRAGMA
d9c0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 synchronous | P
d9d0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
d9e0: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 s=OFF] is set, b
d9f0: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 ut most .** VFSe
da00: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 s do not need th
da10: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 is signal and sh
da20: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
da30: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
da40: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
da50: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
da60: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f l [sqlite3_file_
da70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 control()] with
da80: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 this.** opcode a
da90: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
daa0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
dab0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
dac0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a ialized VFSes.**
dad0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
dae0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
daf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
db00: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
db10: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
db20: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
db30: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
db40: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
db50: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
db60: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
db70: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
db80: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
db90: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
dba0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
dbb0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
dbc0: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
dbd0: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
dbe0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
dbf0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
dc00: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
dc10: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
dc20: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
dc30: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
dc40: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
dc50: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
dc60: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
dc70: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
dc80: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
dc90: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
dca0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
dcb0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
dcc0: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
dcd0: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
dce0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
dcf0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
dd00: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
dd10: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
dd20: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
dd30: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
dd40: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
dd50: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
dd60: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
dd70: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
dd80: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
dd90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
dda0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
ddb0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
ddc0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
ddd0: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
dde0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
ddf0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
de00: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
de10: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
de20: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
de30: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
de40: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
de50: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
de60: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
de70: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
de80: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
de90: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
dea0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
deb0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
dec0: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
ded0: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
dee0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
def0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
df00: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
df10: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
df20: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
df30: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
df40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
df50: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d TL_PERSIST_WAL]]
df60: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
df70: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
df80: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 AL] opcode is us
df90: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
dfa0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
dfb0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 tent [WAL | Writ
dfc0: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 e Ahead Log] set
dfd0: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c ting. By defaul
dfe0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 t, the auxiliary
dff0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 .** write ahead
e000: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d log and shared m
e010: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 emory files used
e020: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e for transaction
e030: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 control.** are
e040: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
e050: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c leted when the l
e060: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e atest connection
e070: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
e080: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 .** closes. Set
e090: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 ting persistent
e0a0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 WAL mode causes
e0b0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 those files to p
e0c0: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 ersist after.**
e0d0: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 close. Persisti
e0e0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 ng the files is
e0f0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 useful when othe
e100: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 r processes that
e110: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 do not.** have
e120: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e write permission
e130: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 on the director
e140: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 y containing the
e150: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
e160: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 ant.** to read t
e170: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
e180: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 , as the WAL and
e190: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
e1a0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a iles must exist.
e1b0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 ** in order for
e1c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 the database to
e1d0: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 be readable. Th
e1e0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
e1f0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
e200: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
e210: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
e220: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
e230: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
e240: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
e250: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
e260: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 able persistent
e270: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f WAL mode or 1 to
e280: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 enable persiste
e290: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 nt.** WAL mode.
e2a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
e2b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
e2c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
e2d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
e2e0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 * WAL persistenc
e2f0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
e300: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e310: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
e320: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
e330: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
e340: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
e350: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
e360: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
e370: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
e380: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
e390: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
e3a0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
e3b0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
e3c0: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
e3d0: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
e3e0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
e3f0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
e400: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
e410: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
e420: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
e430: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
e440: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
e450: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
e460: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
e470: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
e480: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
e490: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
e4a0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
e4b0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
e4c0: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
e4d0: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
e4e0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
e4f0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
e500: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
e510: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
e520: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
e530: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
e540: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
e550: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d CNTL_OVERWRITE]]
e560: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
e570: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
e580: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f ] opcode is invo
e590: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 ked by SQLite af
e5a0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 ter opening.** a
e5b0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 write transacti
e5c0: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 on to indicate t
e5d0: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 hat, unless it i
e5e0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f s rolled back fo
e5f0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e r some.** reason
e600: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 , the entire dat
e610: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
e620: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 be overwritten b
e630: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a y the current .*
e640: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 * transaction. T
e650: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 his is used by V
e660: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 ACUUM operations
e670: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
e680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
e690: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ME]].** ^The [SQ
e6a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
e6b0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 ME] opcode can b
e6c0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
e6d0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a the names of.**
e6e0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 all [VFSes] in
e6f0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 the VFS stack.
e700: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 The names are of
e710: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 all VFS shims a
e720: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 nd the.** final
e730: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 bottom-level VFS
e740: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 are written int
e750: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
e760: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
e770: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
e780: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 d the result is
e790: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 stored in the ch
e7a0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 ar* variable.**
e7b0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 that the fourth
e7c0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 parameter of [sq
e7d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
e7e0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e ol()] points to.
e7f0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 .** The caller i
e800: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
e810: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 r freeing the me
e820: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 mory when done.
e830: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 As with.** all
e840: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 file-control act
e850: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e ions, there is n
e860: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 o guarantee that
e870: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 this will actua
e880: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 lly.** do anythi
e890: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f ng. Callers sho
e8a0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 uld initialize t
e8b0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
e8c0: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e to a NULL.** p
e8d0: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 ointer in case t
e8e0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
e8f0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e is not implemen
e900: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d ted. This file-
e910: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e control.** is in
e920: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e tended for diagn
e930: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a ostic use only..
e940: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
e950: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
e960: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
e970: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
e980: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
e990: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
e9a0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
e9b0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
e9c0: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
e9d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
e9e0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
e9f0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
ea00: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
ea10: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
ea20: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
ea30: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
ea40: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
ea50: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ea60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
ea70: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
ea80: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
ea90: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
eaa0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
eab0: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
eac0: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
ead0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
eae0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
eaf0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
eb00: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
eb10: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
eb20: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
eb30: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
eb40: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
eb50: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
eb60: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
eb70: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
eb80: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
eb90: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
eba0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
ebb0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
ebc0: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
ebd0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
ebe0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
ebf0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
ec00: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
ec10: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
ec20: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
ec30: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
ec40: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
ec50: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
ec60: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
ec70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ec80: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
ec90: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
eca0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
ecb0: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
ecc0: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
ecd0: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
ece0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
ecf0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
ed00: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
ed10: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
ed20: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
ed30: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
ed40: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
ed50: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
ed60: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
ed70: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
ed80: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
ed90: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 d statement. ^I
eda0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
edb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
edc0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
edd0: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 .** any result c
ede0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ode other than [
edf0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 SQLITE_OK] or [S
ee00: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
ee10: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
ee20: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f hat the VFS enco
ee30: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 untered an error
ee40: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 while handling
ee50: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 the [PRAGMA] and
ee60: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 the.** compilat
ee70: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d ion of the PRAGM
ee80: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 A fails with an
ee90: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 error. ^The [SQ
eea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
eeb0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
eec0: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 ol occurs at the
eed0: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 beginning of pr
eee0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 agma statement a
eef0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a nalysis and so.*
ef00: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 * it is able to
ef10: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 override built-i
ef20: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 n [PRAGMA] state
ef30: 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a ments..** </ul>.
ef40: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
ef50: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
ef60: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 DLER]].** ^This
ef70: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 file-control may
ef80: 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 be invoked by S
ef90: 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 QLite on the dat
efa0: 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c abase file handl
efb0: 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 e.** shortly aft
efc0: 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 er it is opened
efd0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 in order to prov
efe0: 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 ide a custom VFS
eff0: 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 with access.**
f000: 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f to the connectio
f010: 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 ns busy-handler
f020: 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 callback. The ar
f030: 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 gument is of typ
f040: 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d e (void **).** -
f050: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f an array of two
f060: 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 (void *) values
f070: 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 . The first (voi
f080: 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f d *) actually po
f090: 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e ints.** to a fun
f0a0: 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 ction of type (i
f0b0: 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e nt (*)(void *)).
f0c0: 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 In order to inv
f0d0: 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 oke the connecti
f0e0: 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 ons.** busy-hand
f0f0: 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ler, this functi
f100: 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 on should be inv
f110: 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 oked with the se
f120: 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e cond (void *) in
f130: 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 .** the array as
f140: 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 the only argume
f150: 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e nt. If it return
f160: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
f170: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a the operation.*
f180: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 * should be retr
f190: 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 ied. If it retur
f1a0: 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 ns zero, the cus
f1b0: 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 tom VFS should a
f1c0: 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 bandon the.** cu
f1d0: 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e rrent operation.
f1e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
f1f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
f200: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
f210: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
f220: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_GET_LOCKPROXYF
f230: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ILE
f240: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
f250: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _SET_LOCKPROXYFI
f260: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 LE 3
f270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f280: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
f290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 4.
f2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
f2b0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 CNTL_SIZE_HINT
f2c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
f2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
f2e0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 NTL_CHUNK_SIZE
f2f0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
f300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
f310: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 TL_FILE_POINTER
f320: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
f330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
f340: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 L_SYNC_OMITTED
f350: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 8.#def
f360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
f370: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 _WIN32_AV_RETRY
f380: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
f390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
f3a0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 PERSIST_WAL
f3b0: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 10.#defin
f3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f e SQLITE_FCNTL_O
f3d0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 VERWRITE
f3e0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 11.#define
f3f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 SQLITE_FCNTL_VF
f400: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 SNAME
f410: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 12.#define
f420: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
f430: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
f440: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 13.#define S
f450: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
f460: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MA
f470: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 14.#define SQ
f480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
f490: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 ANDLER
f4a0: 20 20 31 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 15../*.** CAPI
f4b0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 3REF: Mutex Hand
f4c0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 le.**.** The mut
f4d0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e ex module within
f4e0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 SQLite defines
f4f0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
f500: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 to be an.** abst
f510: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 ract type for a
f520: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 mutex object. T
f530: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e he SQLite core n
f540: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 ever looks.** at
f550: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
f560: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 presentation of
f570: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 an [sqlite3_mute
f580: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 x]. It only.**
f590: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 deals with point
f5a0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ers to the [sqli
f5b0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 te3_mutex] objec
f5c0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 t..**.** Mutexes
f5d0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 are created usi
f5e0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
f5f0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 x_alloc()]..*/.t
f600: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
f610: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 lite3_mutex sqli
f620: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a te3_mutex;../*.*
f630: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
f640: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a nterface Object.
f650: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
f660: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 e of the sqlite3
f670: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 _vfs object defi
f680: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
f690: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 e between.** the
f6a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 SQLite core and
f6b0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
f6c0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
f6d0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 . The "vfs".**
f6e0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 in the name of t
f6f0: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 he object stands
f700: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 for "virtual fi
f710: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 le system". See
f720: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 .** the [VFS | V
f730: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e FS documentation
f740: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e ] for further in
f750: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
f760: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 The value of th
f770: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
f780: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 is initially 1
f790: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
f7a0: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 r in.** future v
f7b0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
f7c0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 e. Additional f
f7d0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
f7e0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a ended to this.**
f7f0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 object when the
f800: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 iVersion value
f810: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e is increased. N
f820: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 ote that the str
f830: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 ucture.** of the
f840: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
f850: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 ect changes in t
f860: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 he transaction b
f870: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 etween.** SQLite
f880: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 version 3.5.9 a
f890: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 nd 3.6.0 and yet
f8a0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
f8b0: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d eld was not.** m
f8c0: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 odified..**.** T
f8d0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c he szOsFile fiel
f8e0: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 d is the size of
f8f0: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 the subclassed
f900: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a [sqlite3_file].*
f910: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 * structure used
f920: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d by this VFS. m
f930: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 xPathname is the
f940: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
f950: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 of.** a pathname
f960: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a in this VFS..**
f970: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 .** Registered s
f980: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 qlite3_vfs objec
f990: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 ts are kept on a
f9a0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 linked list for
f9b0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e med by.** the pN
f9c0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ext pointer. Th
f9d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 e [sqlite3_vfs_r
f9e0: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e egister()].** an
f9f0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 d [sqlite3_vfs_u
fa00: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 nregister()] int
fa10: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 erfaces manage t
fa20: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 his list.** in a
fa30: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 thread-safe way
fa40: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
fa50: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 vfs_find()] inte
fa60: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 rface.** searche
fa70: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 s the list. Nei
fa80: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 ther the applica
fa90: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 tion code nor th
faa0: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 e VFS.** impleme
fab0: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 ntation should u
fac0: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 se the pNext poi
fad0: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
fae0: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 pNext field is t
faf0: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e he only field in
fb00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
fb10: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 .** structure th
fb20: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 at SQLite will e
fb30: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c ver modify. SQL
fb40: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 ite will only ac
fb50: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 cess.** or modif
fb60: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 y this field whi
fb70: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 le holding a par
fb80: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d ticular static m
fb90: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 utex..** The app
fba0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
fbb0: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 never modify any
fbc0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 thing within the
fbd0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
fbe0: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 object once the
fbf0: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 object has been
fc00: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a registered..**.*
fc10: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c * The zName fiel
fc20: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 d holds the name
fc30: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 of the VFS modu
fc40: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 le. The name mu
fc50: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 st.** be unique
fc60: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d across all VFS m
fc70: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b odules..**.** [[
fc80: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
fc90: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 n]].** ^SQLite g
fca0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
fcb0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
fcc0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a ameter to xOpen.
fcd0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e ** is either a N
fce0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 ULL pointer or s
fcf0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a tring obtained.*
fd00: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 * from xFullPath
fd10: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f name() with an o
fd20: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 ptional suffix a
fd30: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 dded..** ^If a s
fd40: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 uffix is added t
fd50: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 o the zFilename
fd60: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 parameter, it wi
fd70: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 ll.** consist of
fd80: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 a single "-" ch
fd90: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 aracter followed
fda0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e by no more than
fdb0: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 .** 11 alphanume
fdc0: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 ric and/or "-" c
fdd0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 haracters..** ^S
fde0: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 QLite further gu
fdf0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a arantees that.**
fe00: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c the string will
fe10: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e be valid and un
fe20: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 changed until xC
fe30: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c lose() is.** cal
fe40: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 led. Because of
fe50: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
fe60: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 tence,.** the [s
fe70: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e qlite3_file] can
fe80: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 safely store a
fe90: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a pointer to the.*
fea0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 * filename if it
feb0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 needs to rememb
fec0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 er the filename
fed0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e for some reason.
fee0: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 .** If the zFile
fef0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 name parameter t
ff00: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c o xOpen is a NUL
ff10: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 L pointer then x
ff20: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 Open.** must inv
ff30: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 ent its own temp
ff40: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 orary name for t
ff50: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 he file. ^Whene
ff60: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c ver the .** xFil
ff70: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
ff80: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 is NULL it will
ff90: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 also be the case
ffa0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 that the.** fla
ffb0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c gs parameter wil
ffc0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 l include [SQLIT
ffd0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
ffe0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 LOSE]..**.** The
fff0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
10000 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 to xOpen() inclu
10010 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 des all bits set
10020 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 in.** the flags
10030 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
10040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
10050 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 . Or if [sqlite
10060 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 3_open()].** or
10070 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
10080 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e )] is used, then
10090 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 flags includes
100a0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c at least.** [SQL
100b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
100c0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
100d0 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 EN_CREATE]. .**
100e0 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 If xOpen() opens
100f0 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c a file read-onl
10100 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a y then it sets *
10110 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 pOutFlags to.**
10120 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
10130 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 OPEN_READONLY].
10140 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a Other bits in *
10150 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 pOutFlags may be
10160 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 set..**.** ^(SQ
10170 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 Lite will also a
10180 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
10190 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
101a0 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 the xOpen().**
101b0 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 call, depending
101c0 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 on the object be
101d0 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a ing opened:.**.*
101e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
101f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
10200 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b N_DB].** <li> [
10210 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
10220 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
10230 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
10240 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e TEMP_DB].** <li>
10250 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
10260 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 EMP_JOURNAL].**
10270 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
10280 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d EN_TRANSIENT_DB]
10290 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
102a0 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
102b0 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
102c0 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
102d0 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
102e0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 [SQLITE_OPEN_W
102f0 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a AL].** </ul>)^.*
10300 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f *.** The file I/
10310 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e O implementation
10320 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a can use the obj
10330 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 ect type flags t
10340 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 o.** change the
10350 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 way it deals wit
10360 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 h files. For ex
10370 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
10380 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f ation.** that do
10390 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 es not care abou
103a0 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 t crash recovery
103b0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 or rollback mig
103c0 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f ht make.** the o
103d0 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c pen of a journal
103e0 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 file a no-op.
103f0 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a Writes to this j
10400 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 ournal would.**
10410 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 also be no-ops,
10420 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 and any attempt
10430 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 to read the jour
10440 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e nal would return
10450 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 .** SQLITE_IOERR
10460 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d . Or the implem
10470 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 entation might r
10480 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 ecognize that a
10490 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
104a0 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 will be doing p
104b0 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 age-aligned sect
104c0 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 or reads and wri
104d0 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a tes in a random.
104e0 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 ** order and set
104f0 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 up its I/O subs
10500 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c ystem accordingl
10510 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 y..**.** SQLite
10520 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f might also add o
10530 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
10540 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
10550 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a xOpen method:.*
10560 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
10570 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 > [SQLITE_OPEN_D
10580 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
10590 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
105a0 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a EN_EXCLUSIVE].**
105b0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
105c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
105d0 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 LETEONCLOSE] fla
105e0 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 g means the file
105f0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 should be.** de
10600 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 leted when it is
10610 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b closed. ^The [
10620 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
10630 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 TEONCLOSE].** wi
10640 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 ll be set for TE
10650 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 MP databases and
10660 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c their journals,
10670 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 transient.** da
10680 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 tabases, and sub
10690 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 journals..**.**
106a0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
106b0 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 N_EXCLUSIVE] fla
106c0 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 g is always used
106d0 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a in conjunction.
106e0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
106f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
10700 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 flag, which are
10710 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a both directly.*
10720 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 * analogous to t
10730 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f he O_EXCL and O_
10740 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 CREAT flags of t
10750 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a he POSIX open().
10760 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c ** API. The SQL
10770 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
10780 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 VE flag, when pa
10790 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a ired with the .*
107a0 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 * SQLITE_OPEN_CR
107b0 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f EATE, is used to
107c0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 indicate that f
107d0 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 ile should alway
107e0 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c s.** be created,
107f0 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 and that it is
10800 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 an error if it a
10810 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a lready exists..*
10820 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f * It is <i>not</
10830 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 i> used to indic
10840 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f ate the file sho
10850 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a uld be opened .*
10860 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
10870 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 access..**.** ^A
10880 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 t least szOsFile
10890 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
108a0 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 are allocated b
108b0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 y SQLite.** to h
108c0 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 old the [sqlite
108d0 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 3_file] structur
108e0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
108f0 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e third.** argumen
10900 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 t to xOpen. The
10910 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f xOpen method do
10920 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a es not have to.*
10930 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 * allocate the s
10940 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f tructure; it sho
10950 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 uld just fill it
10960 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a in. Note that.
10970 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 ** the xOpen met
10980 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 hod must set the
10990 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
109a0 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 ethods to either
109b0 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c .** a valid [sql
109c0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
109d0 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 object or to NU
109e0 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 LL. xOpen must
109f0 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 do.** this even
10a00 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c if the open fail
10a10 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 s. SQLite expec
10a20 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 ts that the sqli
10a30 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
10a40 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c s.** element wil
10a50 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 l be valid after
10a60 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 xOpen returns r
10a70 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 egardless of the
10a80 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 success.** or f
10a90 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f ailure of the xO
10aa0 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 pen call..**.**
10ab0 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 [[sqlite3_vfs.xA
10ac0 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 ccess]].** ^The
10ad0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
10ae0 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 o xAccess() may
10af0 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 be [SQLITE_ACCES
10b00 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 S_EXISTS].** to
10b10 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 test for the exi
10b20 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 stence of a file
10b30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 , or [SQLITE_ACC
10b40 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 ESS_READWRITE] t
10b50 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 o.** test whethe
10b60 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 r a file is read
10b70 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
10b80 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
10b90 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f CESS_READ].** to
10ba0 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
10bb0 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 file is at least
10bc0 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 readable. The
10bd0 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a file can be a.*
10be0 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a * directory..**.
10bf0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
10c00 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 always allocate
10c10 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e at least mxPathn
10c20 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 ame+1 bytes for
10c30 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 the.** output bu
10c40 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 ffer xFullPathna
10c50 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 me. The exact s
10c60 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 ize of the outpu
10c70 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 t buffer.** is a
10c80 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 lso passed as a
10c90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 parameter to bot
10ca0 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 h methods. If t
10cb0 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 he output buffer
10cc0 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 .** is not large
10cd0 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 enough, [SQLITE
10ce0 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c _CANTOPEN] shoul
10cf0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 d be returned. S
10d00 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 ince this is.**
10d10 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 handled as a fat
10d20 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 al error by SQLi
10d30 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e te, vfs implemen
10d40 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 tations should e
10d50 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 ndeavor.** to pr
10d60 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 event this by se
10d70 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 tting mxPathname
10d80 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 to a sufficient
10d90 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a ly large value..
10da0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f **.** The xRando
10db0 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 mness(), xSleep(
10dc0 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 ), xCurrentTime(
10dd0 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 ), and xCurrentT
10de0 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e imeInt64().** in
10df0 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 terfaces are not
10e00 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 strictly a part
10e10 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 of the filesyst
10e20 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 em, but they are
10e30 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 .** included in
10e40 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 the VFS structur
10e50 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 e for completene
10e60 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 ss..** The xRand
10e70 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f omness() functio
10e80 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 n attempts to re
10e90 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 turn nBytes byte
10ea0 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 s.** of good-qua
10eb0 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 lity randomness
10ec0 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 into zOut. The
10ed0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a return value is.
10ee0 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 ** the actual nu
10ef0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
10f00 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 randomness obta
10f10 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c ined..** The xSl
10f20 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
10f30 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ses the calling
10f40 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 thread to sleep
10f50 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 for at.** least
10f60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
10f70 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e croseconds given
10f80 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 . ^The xCurrent
10f90 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 Time().** method
10fa0 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 returns a Julia
10fb0 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 n Day Number for
10fc0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
10fd0 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a e and time as.**
10fe0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e a floating poin
10ff0 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 t value..** ^The
11000 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
11010 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 64() method retu
11020 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 rns, as an integ
11030 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a er, the Julian.*
11040 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c * Day Number mul
11050 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 tiplied by 86400
11060 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 000 (the number
11070 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
11080 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 in .** a 24-hour
11090 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c day). .** ^SQL
110a0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 ite will use the
110b0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
110c0 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 64() method to g
110d0 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a et the current.*
110e0 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 * date and time
110f0 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 if that method i
11100 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 s available (if
11110 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 iVersion is 2 or
11120 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 .** greater and
11130 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
11140 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
11150 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c L) and will fall
11160 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 back.** to xCur
11170 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 rentTime() if xC
11180 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
11190 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 ) is unavailable
111a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 ..**.** ^The xSe
111b0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 tSystemCall(), x
111c0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c GetSystemCall(),
111d0 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d and xNestSystem
111e0 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 Call() interface
111f0 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 s.** are not use
11200 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 d by the SQLite
11210 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 core. These opt
11220 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ional interfaces
11230 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a are provided.**
11240 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 by some VFSes t
11250 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 o facilitate tes
11260 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 ting of the VFS
11270 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 code. By overrid
11280 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 ing .** system c
11290 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 alls with functi
112a0 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f ons under its co
112b0 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 ntrol, a test pr
112c0 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d ogram can.** sim
112d0 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 ulate faults and
112e0 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e error condition
112f0 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 s that would oth
11300 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 erwise be diffic
11310 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 ult.** or imposs
11320 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 ible to induce.
11330 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 The set of syst
11340 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 em calls that ca
11350 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a n be overridden.
11360 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f ** varies from o
11370 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 ne VFS to anothe
11380 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 r, and from one
11390 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 version of the s
113a0 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a ame VFS to the.*
113b0 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 * next. Applica
113c0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 tions that use t
113d0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
113e0 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 must be prepared
113f0 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 for any.** or a
11400 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 ll of these inte
11410 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c rfaces to be NUL
11420 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 L or for their b
11430 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 ehavior to chang
11440 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 e.** from one re
11450 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 lease to the nex
11460 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
11470 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 must not attemp
11480 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 t to access.** a
11490 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 ny of these meth
114a0 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 ods if the iVers
114b0 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 ion of the VFS i
114c0 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a s less than 3..*
114d0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
114e0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c sqlite3_vfs sql
114f0 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 ite3_vfs;.typede
11500 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 f void (*sqlite3
11510 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f _syscall_ptr)(vo
11520 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 id);.struct sqli
11530 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 te3_vfs {. int
11540 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 iVersion;
11550 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 /* Structur
11560 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 e version number
11570 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a (currently 3) *
11580 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 /. int szOsFile
11590 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
115a0 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 Size of subclass
115b0 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 ed sqlite3_file
115c0 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e */. int mxPathn
115d0 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ame; /*
115e0 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 Maximum file pa
115f0 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f thname length */
11600 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a . sqlite3_vfs *
11610 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e pNext; /* N
11620 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 ext registered V
11630 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 FS */. const ch
11640 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 ar *zName;
11650 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 /* Name of this
11660 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 virtual file sy
11670 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a stem */. void *
11680 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 pAppData;
11690 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f /* Pointer to
116a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 application-spe
116b0 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 cific data */.
116c0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c int (*xOpen)(sql
116d0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
116e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 char *zName, sq
116f0 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 lite3_file*,.
11700 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 int
11710 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 flags, int *pOut
11720 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a Flags);. int (*
11730 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 xDelete)(sqlite3
11740 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
11750 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 r *zName, int sy
11760 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a ncDir);. int (*
11770 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 xAccess)(sqlite3
11780 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
11790 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c r *zName, int fl
117a0 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 ags, int *pResOu
117b0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c t);. int (*xFul
117c0 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 lPathname)(sqlit
117d0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
117e0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
117f0 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 nOut, char *zOut
11800 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c );. void *(*xDl
11810 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 Open)(sqlite3_vf
11820 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
11830 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f zFilename);. vo
11840 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 id (*xDlError)(s
11850 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
11860 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 nByte, char *zE
11870 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 rrMsg);. void (
11880 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 *(*xDlSym)(sqlit
11890 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 e3_vfs*,void*, c
118a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 onst char *zSymb
118b0 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f ol))(void);. vo
118c0 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 id (*xDlClose)(s
118d0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 qlite3_vfs*, voi
118e0 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 d*);. int (*xRa
118f0 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 ndomness)(sqlite
11900 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
11910 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a e, char *zOut);.
11920 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 int (*xSleep)(
11930 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
11940 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b t microseconds);
11950 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e . int (*xCurren
11960 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 tTime)(sqlite3_v
11970 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 fs*, double*);.
11980 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 int (*xGetLastE
11990 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
119a0 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 s*, int, char *)
119b0 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
119c0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
119d0 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f e in version 1 o
119e0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
119f0 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 object. ** def
11a00 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 inition. Those
11a10 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 that follow are
11a20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e added in version
11a30 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 2 or later. */
11a40 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e . int (*xCurren
11a50 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 tTimeInt64)(sqli
11a60 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 te3_vfs*, sqlite
11a70 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 3_int64*);. /*.
11a80 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
11a90 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
11aa0 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f rsions 1 and 2 o
11ab0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
11ac0 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 object.. ** Th
11ad0 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f ose below are fo
11ae0 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 r version 3 and
11af0 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 greater.. */.
11b00 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d int (*xSetSystem
11b10 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
11b20 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
11b30 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 zName, sqlite3_s
11b40 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 yscall_ptr);. s
11b50 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 qlite3_syscall_p
11b60 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 tr (*xGetSystemC
11b70 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
11b80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
11b90 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 Name);. const c
11ba0 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 har *(*xNextSyst
11bb0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
11bc0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
11bd0 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 *zName);. /*.
11be0 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 ** The methods
11bf0 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 above are in ver
11c00 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 sions 1 through
11c10 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 3 of the sqlite_
11c20 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
11c30 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 New fields may
11c40 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 be appended in f
11c50 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 igure versions.
11c60 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 The iVersion.
11c70 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e ** value will in
11c80 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 crement whenever
11c90 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a this happens. .
11ca0 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 */.};../*.** C
11cb0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
11cc0 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 or the xAccess V
11cd0 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
11ce0 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
11cf0 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 nstants can be u
11d00 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
11d10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
11d20 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
11d30 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 hod of an [sqlit
11d40 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 e3_vfs] object.
11d50 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a They determine.
11d60 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 ** what kind of
11d70 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 permissions the
11d80 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 xAccess method i
11d90 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a s looking for..*
11da0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
11db0 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 CESS_EXISTS, the
11dc0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
11dd0 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 ** simply checks
11de0 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
11df0 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 e exists..** Wit
11e00 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
11e10 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 READWRITE, the x
11e20 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
11e30 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
11e40 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 the named direct
11e50 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 ory is both read
11e60 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c able and writabl
11e70 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 e.** (in other w
11e80 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 ords, if files c
11e90 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d an be added, rem
11ea0 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 oved, and rename
11eb0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 d within.** the
11ec0 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 directory)..** T
11ed0 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 he SQLITE_ACCESS
11ee0 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 _READWRITE const
11ef0 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ant is currently
11f00 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 used only by th
11f10 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 e.** [temp_store
11f20 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d _directory pragm
11f30 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 a], though this
11f40 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 could change in
11f50 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 a future.** rele
11f60 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ase of SQLite..*
11f70 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
11f80 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 CESS_READ, the x
11f90 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a Access method.**
11fa0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
11fb0 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 the file is read
11fc0 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 able. The SQLIT
11fd0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f E_ACCESS_READ co
11fe0 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 nstant is.** cur
11ff0 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 rently unused, t
12000 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 hough it might b
12010 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 e used in a futu
12020 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
12030 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 SQLite..*/.#def
12040 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
12050 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 S_EXISTS 0.#d
12060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
12070 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 ESS_READWRITE 1
12080 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 /* Used by PRA
12090 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 GMA temp_store_d
120a0 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 irectory */.#def
120b0 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ine SQLITE_ACCES
120c0 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 S_READ 2
120d0 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a /* Unused */../*
120e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
120f0 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d ags for the xShm
12100 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a Lock VFS method.
12110 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
12120 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ger constants de
12130 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 fine the various
12140 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 locking operati
12150 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 ons.** allowed b
12160 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d y the xShmLock m
12170 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 ethod of [sqlite
12180 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 3_io_methods].
12190 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 The.** following
121a0 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 are the only le
121b0 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 gal combinations
121c0 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 of flags to the
121d0 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 .** xShmLock met
121e0 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a hod:.**.** <ul>.
121f0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
12200 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
12210 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
12220 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
12230 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 _LOCK | SQLITE_S
12240 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 HM_EXCLUSIVE.**
12250 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
12260 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
12270 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c _SHM_SHARED.** <
12280 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
12290 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f UNLOCK | SQLITE_
122a0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
122b0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 </ul>.**.** Whe
122c0 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 n unlocking, the
122d0 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 same SHARED or
122e0 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d EXCLUSIVE flag m
122f0 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 ust be supplied
12300 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 as.** was given
12310 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e no the correspon
12320 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a ding lock. .**.
12330 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
12340 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 method can trans
12350 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e ition between un
12360 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 locked and SHARE
12370 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 D or.** between
12380 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 unlocked and EXC
12390 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e LUSIVE. It cann
123a0 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 ot transition be
123b0 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 tween SHARED.**
123c0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a and EXCLUSIVE..*
123d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
123e0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 _SHM_UNLOCK
123f0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
12400 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 TE_SHM_LOCK
12410 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
12420 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 LITE_SHM_SHARED
12430 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
12440 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 SQLITE_SHM_EXCLU
12450 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a SIVE 8../*.**
12460 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d CAPI3REF: Maxim
12470 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 um xShmLock inde
12480 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d x.**.** The xShm
12490 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b Lock method on [
124a0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
124b0 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 ds] may use valu
124c0 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 es.** between 0
124d0 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 and this upper b
124e0 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 ound as its "off
124f0 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a set" argument..*
12500 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
12510 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 e will never att
12520 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 empt to acquire
12530 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 or release a.**
12540 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 lock outside of
12550 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 this range.*/.#d
12560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
12570 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a _NLOCK 8.
12580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
12590 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 : Initialize The
125a0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a SQLite Library.
125b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
125c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
125d0 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 routine initiali
125e0 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 zes the.** SQLit
125f0 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 e library. ^The
12600 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
12610 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 n() routine.** d
12620 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 eallocates any r
12630 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 esources that we
12640 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
12650 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12660 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ze()..** These r
12670 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 outines are desi
12680 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 gned to aid in p
12690 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a rocess initializ
126a0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 ation and.** shu
126b0 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 tdown on embedde
126c0 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b d systems. Work
126d0 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 station applicat
126e0 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 ions using.** SQ
126f0 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f Lite normally do
12700 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 not need to inv
12710 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 oke either of th
12720 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
12730 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
12740 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12750 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
12760 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
12770 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 is.** the first
12780 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 time sqlite3_ini
12790 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
127a0 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 oked during the
127b0 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 lifetime of.** t
127c0 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 he process, or i
127d0 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
127e0 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
127f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
12800 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nvoked.** follow
12810 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 ing a call to sq
12820 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12830 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 . ^(Only an eff
12840 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f ective call.** o
12850 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 f sqlite3_initia
12860 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 lize() does any
12870 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 initialization.
12880 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 All other calls
12890 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 .** are harmless
128a0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
128b0 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
128c0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 e3_shutdown() is
128d0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
128e0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 call if it is th
128f0 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 e first.** call
12900 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
12910 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 own() since the
12920 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 last sqlite3_ini
12930 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e tialize(). ^(On
12940 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 ly.** an effecti
12950 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ve call to sqlit
12960 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f e3_shutdown() do
12970 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c es any deinitial
12980 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 ization..** All
12990 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c other valid call
129a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 s to sqlite3_shu
129b0 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d tdown() are harm
129c0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a less no-ops.)^.*
129d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
129e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e _initialize() in
129f0 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 terface is threa
12a00 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 dsafe, but sqlit
12a10 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a e3_shutdown().**
12a20 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 is not. The sq
12a30 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12a40 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 interface must
12a50 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 only be called f
12a60 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 rom a.** single
12a70 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 thread. All ope
12a80 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
12a90 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 ections] must be
12aa0 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a closed and all.
12ab0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ** other SQLite
12ac0 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 resources must b
12ad0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 e deallocated pr
12ae0 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a ior to invoking.
12af0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 ** sqlite3_shutd
12b00 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f own()..**.** Amo
12b10 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c ng other things,
12b20 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 ^sqlite3_initia
12b30 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f lize() will invo
12b40 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 ke.** sqlite3_os
12b50 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 _init(). Simila
12b60 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 rly, ^sqlite3_sh
12b70 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c utdown().** will
12b80 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
12b90 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 os_end()..**.**
12ba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
12bb0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
12bc0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
12bd0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
12be0 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d ..** ^If for som
12bf0 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 e reason, sqlite
12c00 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
12c10 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 s unable to init
12c20 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 ialize.** the li
12c30 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 brary (perhaps i
12c40 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 t is unable to a
12c50 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 llocate a needed
12c60 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a resource such.*
12c70 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 * as a mutex) it
12c80 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 returns an [err
12c90 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 or code] other t
12ca0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e han [SQLITE_OK].
12cb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
12cc0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
12cd0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
12ce0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
12cf0 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 many other.** S
12d00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
12d10 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c so that an appl
12d20 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 ication usually
12d30 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
12d40 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 .** invoke sqlit
12d50 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12d60 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 directly. For e
12d70 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 xample, [sqlite3
12d80 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c _open()].** call
12d90 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 s sqlite3_initia
12da0 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 lize() so the SQ
12db0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
12dc0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c l be automatical
12dd0 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 ly.** initialize
12de0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
12df0 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 open()] is calle
12e00 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 d if it has not
12e10 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a be initialized.*
12e20 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 * already. ^How
12e30 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 ever, if SQLite
12e40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
12e50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 the [SQLITE_OMI
12e60 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 T_AUTOINIT].** c
12e70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
12e80 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 on, then the aut
12e90 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 omatic calls to
12ea0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12eb0 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 ze().** are omit
12ec0 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c ted and the appl
12ed0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c ication must cal
12ee0 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 l sqlite3_initia
12ef0 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a lize() directly.
12f00 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ** prior to usin
12f10 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
12f20 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
12f30 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 or maximum porta
12f40 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 bility,.** it is
12f50 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
12f60 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 t applications a
12f70 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c lways invoke sql
12f80 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12f90 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 ).** directly pr
12fa0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
12fb0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
12fc0 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 terface. Future
12fd0 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 releases.** of
12fe0 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 SQLite may requi
12ff0 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 re this. In oth
13000 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 er words, the be
13010 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 havior exhibited
13020 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 .** when SQLite
13030 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
13040 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
13050 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 TOINIT] might be
13060 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 come the.** defa
13070 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 ult behavior in
13080 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 some future rele
13090 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ase of SQLite..*
130a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
130b0 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 _os_init() routi
130c0 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e ne does operatin
130d0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
130e0 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 c.** initializat
130f0 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
13100 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 e library. The
13110 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
13120 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f .** routine undo
13130 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
13140 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
13150 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 (). Typical tas
13160 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ks.** performed
13170 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 by these routine
13180 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 s include alloca
13190 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tion or dealloca
131a0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 tion.** of stati
131b0 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 c resources, ini
131c0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 tialization of g
131d0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c lobal variables,
131e0 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 .** setting up a
131f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
13200 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 3_vfs] module, o
13210 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 r setting up.**
13220 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 a default config
13230 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 uration using [s
13240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
13260 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
13270 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 ever invoke eith
13280 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e er sqlite3_os_in
13290 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 it().** or sqlit
132a0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 e3_os_end() dire
132b0 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 ctly. The appli
132c0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e cation should on
132d0 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ly invoke.** sql
132e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
132f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 ) and sqlite3_sh
13300 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 utdown(). The s
13310 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
13320 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
13330 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 called automati
13340 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
13350 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
13360 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f d.** sqlite3_os_
13370 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 end() is called
13380 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 by sqlite3_shutd
13390 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 own(). Appropri
133a0 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ate.** implement
133b0 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 ations for sqlit
133c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
133d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
133e0 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 ).** are built i
133f0 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 nto SQLite when
13400 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 it is compiled f
13410 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 or Unix, Windows
13420 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 , or OS/2..** Wh
13430 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 en [custom build
13440 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 s | built for ot
13450 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a her platforms].*
13460 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 * (using the [SQ
13470 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d LITE_OS_OTHER=1]
13480 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
13490 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 option) the app
134a0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 lication must su
134b0 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 pply a suitable
134c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 implementation f
134d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 or.** sqlite3_os
134e0 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
134f0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 te3_os_end(). A
13500 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 n application-su
13510 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d pplied.** implem
13520 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
13530 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 te3_os_init() or
13540 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
13550 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e ).** must return
13560 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
13570 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 success and some
13580 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f other [error co
13590 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c de] upon.** fail
135a0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ure..*/.SQLITE_A
135b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 PI int sqlite3_i
135c0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
135d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
135e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
135f0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
13600 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f PI int sqlite3_o
13610 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 s_init(void);.SQ
13620 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
13630 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
13640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
13650 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
13660 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
13670 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
13680 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
13690 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
136a0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
136b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
136c0 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
136d0 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
136e0 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
136f0 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
13700 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
13710 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
13720 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
13730 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
13740 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
13750 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
13760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
13770 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
13780 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
13790 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
137a0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
137b0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
137c0 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
137d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
137e0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
137f0 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
13800 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
13810 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
13820 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
13830 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
13840 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
13850 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
13860 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
13870 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
13880 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
13890 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
138a0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
138b0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
138c0 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
138d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
138e0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
138f0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
13900 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
13910 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
13920 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
13930 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
13940 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
13950 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
13960 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
13970 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
13980 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
13990 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
139a0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
139b0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
139c0 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
139d0 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
139e0 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
139f0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
13a00 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
13a10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
13a20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
13a30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
13a40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
13a50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
13a60 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
13a70 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e * [configuration
13a80 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
13a90 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
13aa0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
13ab0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
13ac0 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
13ad0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
13ae0 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
13af0 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 on the [configu
13b00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
13b10 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
13b20 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
13b30 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 When a configura
13b40 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 tion option is s
13b50 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 et, sqlite3_conf
13b60 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 ig() returns [SQ
13b70 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
13b80 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
13b90 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
13ba0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
13bb0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
13bc0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
13bd0 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
13be0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
13bf0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
13c00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e int sqlite3_con
13c10 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
13c20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13c30 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
13c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
13c50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
13c60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
13c70 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
13c80 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
13c90 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
13ca0 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
13cb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
13cc0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
13cd0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
13ce0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
13cf0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
13d00 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
13d10 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
13d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13d30 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
13d40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
13d50 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nt)..**.** The s
13d60 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
13d70 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
13d80 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 fig(D,V,...) is
13d90 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
13da0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
13db0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 DE | configurati
13dc0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e on verb] - an in
13dd0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 teger code .** t
13de0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
13df0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 at aspect of the
13e00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13e10 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
13e20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 configured..** S
13e30 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
13e40 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 nts vary dependi
13e50 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 ng on the config
13e60 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a uration verb..**
13e70 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 .** ^Calls to sq
13e80 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
13e90 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
13ea0 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 OK if and only i
13eb0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 f.** the call is
13ec0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 considered succ
13ed0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 essful..*/.SQLIT
13ee0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
13ef0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
13f00 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
13f10 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
13f20 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
13f30 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
13f40 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
13f50 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
13f60 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
13f70 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
13f80 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
13f90 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
13fa0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
13fb0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
13fc0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
13fd0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
13fe0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
13ff0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
14000 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
14010 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
14020 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
14030 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
14040 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
14050 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
14060 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
14070 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
14080 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
14090 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
140a0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
140b0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
140c0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
140d0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
140e0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
140f0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
14100 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
14110 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
14120 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
14130 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
14140 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
14150 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
14160 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
14170 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
14180 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
14190 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
141a0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
141b0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
141c0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
141d0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
141e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
141f0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
14200 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
14210 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
14220 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
14230 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
14240 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
14250 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
14260 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
14270 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
14280 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
14290 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
142a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
142b0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
142c0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
142d0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
142e0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
142f0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
14300 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
14310 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
14320 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
14330 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
14340 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
14350 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
14360 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
14370 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
14380 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
14390 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
143a0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
143b0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c e xMalloc, xReal
143c0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d loc, and xFree m
143d0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
143e0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
143f0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
14400 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
14410 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
14420 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
14430 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 y..** ^SQLite gu
14440 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
14450 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
14460 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
14470 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
14480 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
14490 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
144a0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 Roundup..**.** x
144b0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
144c0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
144d0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
144e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
144f0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
14500 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
14510 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
14520 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
14530 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
14540 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
14550 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
14560 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
14570 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
14580 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
14590 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
145a0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
145b0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
145c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
145d0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
145e0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
145f0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
14600 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
14610 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
14620 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
14630 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
14640 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
14650 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
14660 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
14670 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
14680 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
14690 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
146a0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
146b0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
146c0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
146d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
146e0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
146f0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
14700 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
14710 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
14720 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
14730 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
14740 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
14750 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
14760 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
14770 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
14780 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
14790 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
147a0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a (For example,.**
147b0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
147c0 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
147d0 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
147e0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
147f0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
14800 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
14810 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
14820 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
14830 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
14840 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
14850 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
14860 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
14870 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
14880 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
14890 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
148a0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
148b0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
148c0 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
148d0 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
148e0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
148f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
14900 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
14910 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
14920 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
14930 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
14940 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
14950 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
14960 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
14970 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
14980 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
14990 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
149a0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
149b0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
149c0 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
149d0 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
149e0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
149f0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
14a00 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
14a10 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
14a20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
14a30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14a40 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
14a50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
14a60 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
14a70 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
14a80 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
14a90 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
14aa0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
14ab0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
14ac0 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
14ad0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
14ae0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
14af0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
14b00 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
14b10 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
14b20 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
14b30 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
14b40 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
14b50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
14b60 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
14b70 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
14b80 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
14b90 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
14ba0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
14bb0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
14bc0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
14bd0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
14be0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14bf0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
14c00 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
14c10 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
14c20 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
14c30 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
14c40 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
14c50 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
14c60 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
14c70 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
14c80 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
14c90 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
14ca0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
14cb0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
14cc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
14cd0 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
14ce0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
14cf0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
14d00 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
14d10 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
14d20 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
14d30 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
14d40 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
14d50 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
14d60 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
14d70 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
14d80 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
14d90 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
14da0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
14db0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
14dc0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
14dd0 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
14de0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
14df0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
14e00 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
14e10 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
14e20 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
14e30 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
14e40 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
14e50 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
14e60 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
14e70 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
14e80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
14e90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
14ea0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
14eb0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
14ec0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14ed0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
14ee0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
14ef0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
14f00 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
14f10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
14f20 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
14f30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14f40 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
14f50 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
14f60 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
14f70 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
14f80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14f90 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
14fa0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
14fb0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
14fc0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
14fd0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
14fe0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
14ff0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
15000 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
15010 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
15020 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
15030 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
15040 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
15050 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
15060 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
15070 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
15080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15090 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
150a0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
150b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
150c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
150d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
150e0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
150f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
15100 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
15110 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
15120 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
15130 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
15140 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
15150 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
15160 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
15170 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
15180 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
15190 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
151a0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
151b0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
151c0 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
151d0 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
151e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
151f0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
15200 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
15210 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
15220 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
15230 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
15240 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
15250 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
15260 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
15270 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
15280 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
15290 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
152a0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
152b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
152c0 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
152d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
152e0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
152f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
15300 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
15310 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
15320 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
15330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15340 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
15350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
15360 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
15370 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
15380 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
15390 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
153a0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
153b0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
153c0 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
153d0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
153e0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
153f0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
15400 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
15410 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
15420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
15430 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
15440 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
15450 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
15460 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
15470 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
15480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15490 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
154a0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
154b0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
154c0 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
154d0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
154e0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
154f0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
15500 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
15510 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
15520 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
15530 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
15540 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
15550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
15560 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
15570 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
15580 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
15590 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
155a0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
155b0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
155c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
155d0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
155e0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
155f0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
15600 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
15610 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
15620 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15630 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
15640 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
15650 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
15660 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
15670 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
15680 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15690 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
156a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
156b0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
156d0 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
156e0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
156f0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
15700 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
15710 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
15720 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
15730 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
15740 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
15750 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
15760 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
15770 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
15780 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
15790 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
157a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
157b0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
157c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
157d0 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
157e0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
157f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
15800 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
15810 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
15820 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
15830 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
15840 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
15850 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
15860 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
15870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
15880 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
15890 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
158a0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
158b0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
158c0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
158d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
158e0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
158f0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
15900 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
15910 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
15920 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
15930 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
15940 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
15950 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
15960 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
15970 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
15980 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15990 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
159a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
159b0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
159c0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
159d0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
159e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
159f0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
15a00 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
15a10 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
15a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
15a30 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
15a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
15a50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15a60 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
15a70 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15a80 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
15a90 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
15aa0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
15ab0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
15ac0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
15ad0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
15ae0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
15af0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
15b00 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
15b10 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
15b20 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
15b30 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
15b40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
15b50 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
15b60 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
15b70 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
15b80 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
15b90 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
15ba0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 te.)^ ^SQLite ma
15bb0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 kes.** its own p
15bc0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
15bd0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
15be0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
15bf0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
15c00 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 e.** before the
15c10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15c20 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e )] call returns.
15c30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15c50 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
15c60 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
15c70 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
15c80 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
15c90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
15ca0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
15cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
15cc0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
15cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
15ce0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
15cf0 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 re. The [sqlite
15d00 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
15d10 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
15d20 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
15d30 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
15d40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
15d50 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
15d60 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
15d70 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
15d80 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
15d90 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
15da0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
15db0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
15dc0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
15dd0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
15de0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
15df0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
15e00 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
15e10 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
15e20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
15e30 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
15e40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
15e50 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
15e60 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
15e70 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
15e80 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
15e90 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 t, interpreted a
15ea0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c s a .** boolean,
15eb0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f which enables o
15ec0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 r disables the c
15ed0 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d ollection of mem
15ee0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a ory allocation .
15ef0 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e ** statistics. ^
15f00 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c (When memory all
15f10 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
15f20 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c cs are disabled,
15f30 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 the .** followi
15f40 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ng SQLite interf
15f50 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d aces become non-
15f60 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
15f70 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
15f80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
15f90 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
15fa0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
15fb0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
15fc0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
15fd0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
15fe0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 it64()].** <li
15ff0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
16000 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 s()].** </ul>)
16010 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c ^.** ^Memory all
16020 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
16030 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 cs are enabled b
16040 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 y default unless
16050 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f SQLite is.** co
16060 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
16070 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 ITE_DEFAULT_MEMS
16080 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 TATUS]=0 in whic
16090 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a h case memory.**
160a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
160b0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
160c0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
160d0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
160e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
160f0 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c CRATCH]] <dt>SQL
16100 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
16110 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 CH</dt>.** <dd>
16120 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
16130 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
16140 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
16150 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
16160 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 e for.** scratch
16170 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 memory. There
16180 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
16190 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 nts: A pointer
161a0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 an 8-byte.** ali
161b0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 gned memory buff
161c0 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 er from which th
161d0 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
161e0 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a tions will be.**
161f0 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 drawn, the size
16200 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 of each scratch
16210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 allocation (sz)
16220 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 ,.** and the max
16230 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 imum number of s
16240 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
16250 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a ns (N). The sz.
16260 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
16270 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f be a multiple o
16280 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 f 16..** The fir
16290 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
162a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
162b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e an 8-byte align
162c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 ed buffer.** of
162d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
162e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
162f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
16300 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 se no more than
16310 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 two scratch buff
16320 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 ers per thread.
16330 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 So.** N should
16340 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 be set to twice
16350 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 the expected max
16360 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
16370 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 hreads..** ^SQLi
16380 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 te will never re
16390 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 quire a scratch
163a0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d buffer that is m
163b0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 ore than 6.** ti
163c0 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 mes the database
163d0 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 page size. ^If
163e0 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 SQLite needs nee
163f0 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a ds additional.**
16400 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
16410 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
16420 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
16430 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16440 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b tion, then .** [
16450 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16460 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 ] will be used t
16470 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d o obtain the mem
16480 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e ory needed.</dd>
16490 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
164a0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
164b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
164c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
164d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
164e0 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
164f0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
16500 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
16510 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
16520 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
16530 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
16540 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
16550 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
16560 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 ntation. .** Th
16570 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
16580 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
16590 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 sed if an applic
165a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 ation-define pag
165b0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
165c0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 mentation is loa
165d0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 ded using the SQ
165e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
165f0 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 HE2 option..** T
16600 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
16610 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
16620 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 option: A point
16630 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 er to 8-byte ali
16640 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 gned.** memory,
16650 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
16660 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a page buffer (sz
16670 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
16680 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a r of pages (N)..
16690 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
166a0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
166b0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
166c0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
166d0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
166e0 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
166f0 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 2 and 32768) plu
16700 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 s a little extra
16710 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
16720 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
16730 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 page header size
16740 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 is 20 to 40 byt
16750 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a es depending on.
16760 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 ** the host arch
16770 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 itecture. ^It i
16780 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
16790 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
167a0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 d memory,.** to
167b0 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 make sz a little
167c0 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 too large. The
167d0 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 first.** argume
167e0 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 nt should point
167f0 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e to an allocation
16800 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
16810 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
16820 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
16830 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 ll use the memor
16840 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 y provided by th
16850 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16860 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a to satisfy its.
16870 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 ** memory needs
16880 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 for the first N
16890 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 pages that it ad
168a0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 ds to cache. ^I
168b0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
168c0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
168d0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
168e0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
168f0 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 ded by this opti
16900 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 on, then.** SQLi
16910 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 te goes to [sqli
16920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f te3_malloc()] fo
16930 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c r the additional
16940 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a storage space..
16950 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 ** The pointer i
16960 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
16970 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 ment must.** be
16980 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
16990 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 byte boundary or
169a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
169b0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a vior of SQLite.*
169c0 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 * will be undefi
169d0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
169e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
169f0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
16a00 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
16a10 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
16a20 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
16a30 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
16a40 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
16a50 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
16a60 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
16a70 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 dynamic memory a
16a80 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 llocation needs
16a90 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f beyond those pro
16aa0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 vided.** for by
16ab0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
16ac0 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c CRATCH] and [SQL
16ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
16ae0 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 ACHE]..** There
16af0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
16b00 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 nts: An 8-byte a
16b10 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
16b20 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
16b30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
16b40 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
16b50 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
16b60 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
16b70 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
16b80 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
16b90 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
16ba0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
16bb0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
16bc0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
16bd0 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
16be0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
16bf0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
16c00 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
16c10 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
16c20 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
16c30 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
16c40 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
16c50 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
16c60 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
16c70 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 ot NULL and eith
16c80 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
16c90 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a E_MEMSYS3] or.**
16ca0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
16cb0 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 MEMSYS5] are def
16cc0 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 ined, then the a
16cd0 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
16ce0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 y.** allocator i
16cf0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e s engaged to han
16d00 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 dle all of SQLit
16d10 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 es memory alloca
16d20 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 tion needs..** T
16d30 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
16d40 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
16d50 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c nter) must be al
16d60 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
16d70 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f te.** boundary o
16d80 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
16d90 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 avior of SQLite
16da0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 will be undefine
16db0 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 d..** The minimu
16dc0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
16dd0 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 e is capped at 2
16de0 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 **12. Reasonable
16df0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 values.** for t
16e00 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
16e10 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 ation size are 2
16e20 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 **5 through 2**8
16e30 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
16e40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16e50 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
16e60 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 CONFIG_MUTEX</dt
16e70 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
16e80 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
16e90 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
16ea0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
16eb0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
16ec0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
16ed0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
16ee0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
16ef0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
16f00 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
16f10 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
16f20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
16f30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
16f40 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 ce.** the mutex
16f50 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
16f60 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
16f70 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
16f80 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f opy of the.** co
16f90 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
16fa0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
16fb0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
16fc0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
16fd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
16fe0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
16ff0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
17000 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
17010 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
17020 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
17030 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
17040 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
17050 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
17060 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
17070 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
17080 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
17090 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
170a0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
170b0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
170c0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
170d0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
170e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
170f0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
17100 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
17110 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
17120 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
17130 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
17140 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
17150 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
17160 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
17170 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
17180 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
17190 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
171a0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
171b0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
171c0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
171d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
171e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a mutex_methods].*
171f0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
17200 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
17210 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
17220 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
17230 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
17240 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
17250 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
17260 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f fault mutex allo
17270 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
17280 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
17290 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 r used to track
172a0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 mutex usage for
172b0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 performance.** p
172c0 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 rofiling or test
172d0 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 ing, for example
172e0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 . ^If SQLite i
172f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
17300 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
17310 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
17320 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
17330 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
17340 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
17350 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
17360 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
17370 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
17380 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
17390 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
173a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
173b0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
173c0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f NFIG_GETMUTEX co
173d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
173e0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
173f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
17400 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
17410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
17420 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c KASIDE]] <dt>SQL
17430 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
17440 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
17450 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
17460 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
17470 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
17480 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a ne the default.*
17490 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
174a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b ion for the look
174b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
174c0 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a ocator on each.*
174d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
174e0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 ection]. The fi
174f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
17500 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
17510 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
17520 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
17530 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
17540 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
17550 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
17560 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
17570 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 nnection.)^ ^(T
17580 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
17590 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c the.** <i>defaul
175a0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
175b0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
175c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
175d0 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f SIDE].** verb to
175e0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
175f0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 fig()] can be us
17600 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
17610 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f lookaside.** co
17620 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 nfiguration on i
17630 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 ndividual connec
17640 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a tions.)^ </dd>.*
17650 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
17660 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c NFIG_PCACHE2]] <
17670 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
17680 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a _PCACHE2</dt>.**
17690 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
176a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
176b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
176c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
176d0 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 o.** an [sqlite3
176e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
176f0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 ] object. This
17700 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 object specifies
17710 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a the interface.*
17720 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 * to a custom pa
17730 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
17740 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c ntation.)^ ^SQL
17750 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
17760 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 of the.** objec
17770 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f t and uses it fo
17780 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d r page cache mem
17790 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
177a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
177b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
177c0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c CACHE2]] <dt>SQL
177d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
177e0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
177f0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
17800 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
17810 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
17820 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
17830 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 n.** [sqlite3_pc
17840 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
17850 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
17860 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
17870 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
17880 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
17890 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
178a0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ct.)^ </dd>.**.*
178b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
178c0 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_LOG]] <dt>SQLI
178d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 TE_CONFIG_LOG</d
178e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
178f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
17900 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 G option takes t
17910 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 wo arguments: a
17920 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 pointer to a.**
17930 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
17940 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f call signature o
17950 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c f void(*)(void*,
17960 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 int,const char*)
17970 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e , .** and a poin
17980 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 ter to void. ^If
17990 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
179a0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
179b0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f L, it is.** invo
179c0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ked by [sqlite3_
179d0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 log()] to proces
179e0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 s each logging e
179f0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
17a00 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 * function point
17a10 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 er is NULL, the
17a20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
17a30 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 interface become
17a40 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 s a no-op..** ^T
17a50 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 he void pointer
17a60 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f that is the seco
17a70 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 nd argument to S
17a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
17a90 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 is.** passed th
17aa0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
17ab0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
17ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
17ad0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
17ae0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 * function whene
17af0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f ver that functio
17b00 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e n is invoked. ^
17b10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17b20 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c eter to.** the l
17b30 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 ogger function i
17b40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
17b50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
17b60 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e to the correspon
17b70 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ding.** [sqlite3
17b80 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 _log()] call and
17b90 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
17ba0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 be a [result cod
17bb0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 e] or an.** [ext
17bc0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
17bd0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 e]. ^The third
17be0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
17bf0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 to the logger i
17c00 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 s.** log message
17c10 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e after formattin
17c20 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 g via [sqlite3_s
17c30 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 nprintf()]..** T
17c40 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e he SQLite loggin
17c50 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e g interface is n
17c60 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 ot reentrant; th
17c70 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
17c80 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 n.** supplied by
17c90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
17ca0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 must not invoke
17cb0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
17cc0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d rface..** In a m
17cd0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
17ce0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 plication, the a
17cf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
17d00 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
17d10 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 ction must be th
17d20 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a readsafe. </dd>.
17d30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17d40 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e ONFIG_URI]] <dt>
17d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
17d60 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f I.** <dd> This o
17d70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
17d80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 ngle argument of
17d90 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f type int. If no
17da0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 n-zero, then.**
17db0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 URI handling is
17dc0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 globally enabled
17dd0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 . If the paramet
17de0 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e er is zero, then
17df0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a URI handling.**
17e00 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 is globally dis
17e10 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 abled. If URI ha
17e20 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
17e30 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 ly enabled, all
17e40 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 filenames.** pas
17e50 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f sed to [sqlite3_
17e60 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
17e70 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 3_open_v2()], [s
17e80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
17e90 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 or.** specified
17ea0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 as part of [ATT
17eb0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 ACH] commands ar
17ec0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
17ed0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 URIs, regardles
17ee0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 s.** of whether
17ef0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 or not the [SQLI
17f00 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
17f10 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
17f20 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
17f30 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
17f40 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f ed. If it is glo
17f50 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 bally disabled,
17f60 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a filenames are.**
17f70 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 only interprete
17f80 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 d as URIs if the
17f90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 SQLITE_OPEN_URI
17fa0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
17fb0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 n the.** databas
17fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
17fd0 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 opened. By defau
17fe0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 lt, URI handling
17ff0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 is globally.**
18000 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 disabled. The de
18010 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 fault value may
18020 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f be changed by co
18030 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 mpiling with the
18040 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f .** [SQLITE_USE_
18050 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 URI] symbol defi
18060 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ned..**.** [[SQL
18070 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
18080 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
18090 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
180a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
180b0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 X_SCAN.** <dd> T
180c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 73 20 his option taks
180d0 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 a single integer
180e0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
180f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
18100 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 s.** a boolean i
18110 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c n order to enabl
18120 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
18130 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 use of covering
18140 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 indices for.**
18150 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 full table scans
18160 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 in the query op
18170 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65 timizer. The de
18180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 fault setting is
18190 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 determined.** b
181a0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c y the [SQLITE_AL
181b0 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 LOW_COVERING_IND
181c0 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 EX_SCAN] compile
181d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 -time option, or
181e0 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 is "on".** if t
181f0 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 hat compile-time
18200 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 option is omitt
18210 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 ed..** The abili
18220 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 ty to disable th
18230 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
18240 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 g indices for fu
18250 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a ll table scans.*
18260 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d * is because som
18270 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f e incorrectly co
18280 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 ded legacy appli
18290 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 cations might ma
182a0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c lfunction.** mal
182b0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68 function when th
182c0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 e optimization i
182d0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 s enabled. Prov
182e0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 iding the abilit
182f0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 y to.** disable
18300 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
18310 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 allows the olde
18320 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 r, buggy applica
18330 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 tion code to wor
18340 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 k.** without cha
18350 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 nge even with ne
18360 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
18370 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b SQLite..**.** [[
18380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
18390 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f ACHE]] [[SQLITE_
183a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
183b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
183c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 _CONFIG_PCACHE a
183d0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 nd SQLITE_CONFIG
183e0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 _GETPCACHE.** <d
183f0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 d> These options
18400 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e are obsolete an
18410 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 d should not be
18420 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 used by new code
18430 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 ..** They are re
18440 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
18450 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
18460 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e ty but are now n
18470 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a o-ops..** </dl>.
18480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18490 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
184a0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c HREAD 1 /* nil
184b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
184c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
184d0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 HREAD 2 /* ni
184e0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
184f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
18500 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e LIZED 3 /* n
18510 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
18520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
18530 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 OC 4 /*
18540 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
18550 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
18560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
18570 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f TMALLOC 5 /
18580 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
18590 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
185a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
185b0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 SCRATCH 6
185c0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
185d0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
185e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
185f0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
18600 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
18610 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
18620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18630 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
18640 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
18650 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
18660 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
18670 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
18680 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
18690 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
186a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
186b0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
186c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
186d0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
186e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
186f0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
18700 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
18710 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
18720 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 /./* previously
18730 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 SQLITE_CONFIG_CH
18740 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 UNKALLOC 12 whic
18750 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e h is now unused.
18760 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c */ .#define SQL
18770 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
18780 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 SIDE 13 /* i
18790 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
187a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
187b0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 PCACHE 14
187c0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
187d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
187e0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 IG_GETPCACHE
187f0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 15 /* no-op */.
18800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
18810 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 ONFIG_LOG
18820 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 16 /* xFunc,
18830 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
18840 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18850 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 URI 17
18860 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
18870 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18880 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 _PCACHE2 18
18890 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
188a0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
188b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
188c0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
188d0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 2 19 /* sqlit
188e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
188f0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
18900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
18910 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
18920 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 20 /* int */..
18930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18940 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
18950 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
18960 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
18970 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
18980 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
18990 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
189a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
189b0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
189c0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
189d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
189e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
189f0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
18a00 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
18a10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
18a20 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
18a30 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
18a40 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
18a50 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
18a60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
18a70 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
18a80 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
18a90 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
18aa0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
18ab0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
18ac0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
18ad0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
18ae0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
18af0 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
18b00 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
18b10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
18b20 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
18b30 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
18b40 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
18b50 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
18b60 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
18b70 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
18b80 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
18b90 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
18ba0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
18bb0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
18bc0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
18bd0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
18be0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
18bf0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
18c00 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
18c10 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
18c20 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
18c30 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
18c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
18c50 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
18c60 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
18c70 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
18c80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
18c90 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
18ca0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
18cb0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
18cc0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
18cd0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
18ce0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
18cf0 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
18d00 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
18d10 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
18d20 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
18d30 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
18d40 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
18d50 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
18d60 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
18d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18d80 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
18d90 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
18da0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
18db0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
18dc0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
18dd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
18de0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
18df0 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
18e00 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
18e10 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
18e20 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
18e30 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
18e40 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
18e50 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
18e60 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
18e70 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
18e80 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
18e90 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
18ea0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
18eb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
18ec0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
18ed0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
18ee0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
18ef0 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
18f00 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
18f10 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
18f20 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
18f30 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
18f40 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
18f50 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
18f60 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
18f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18f80 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
18f90 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
18fa0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
18fb0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
18fc0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
18fd0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
18fe0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
18ff0 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
19000 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
19010 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
19020 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
19030 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
19040 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
19050 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
19060 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
19070 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
19080 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
19090 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
190a0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
190b0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
190c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
190d0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
190e0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
190f0 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
19100 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
19110 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
19120 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
19130 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
19140 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
19150 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
19160 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
19170 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
19180 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
19190 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
191a0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
191b0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
191c0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
191d0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
191e0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
191f0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
19200 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
19210 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
19220 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
19230 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
19240 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
19250 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
19260 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
19270 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
19280 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
19290 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
192a0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
192b0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
192c0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
192d0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
192e0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
192f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
19300 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
19310 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
19320 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
19330 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
19340 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
19350 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
19360 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
19370 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
19380 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
19390 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
193a0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
193b0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
193c0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
193d0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
193e0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
193f0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
19400 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
19410 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
19420 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
19430 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
19440 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
19450 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
19460 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
19470 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
19480 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
19490 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
194a0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
194b0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
194c0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
194d0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
194e0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
194f0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
19500 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
19510 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
19520 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
19530 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
19540 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
19550 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
19560 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
19570 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
19580 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
19590 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
195a0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
195b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
195c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
195d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 G_LOOKASIDE
195e0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 1001 /* void*
195f0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
19600 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
19610 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 FIG_ENABLE_FKEY
19620 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 1002 /* int
19630 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
19640 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
19650 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
19660 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
19670 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t* */.../*.** CA
19680 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
19690 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
196a0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
196b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
196c0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
196d0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
196e0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
196f0 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
19700 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
19710 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
19720 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
19730 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
19740 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
19750 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
19760 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
19770 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
19780 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
19790 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
197a0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c result_codes(sql
197b0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 ite3*, int onoff
197c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
197d0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 EF: Last Insert
197e0 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 Rowid.**.** ^Eac
197f0 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 h entry in an SQ
19800 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 Lite table has a
19810 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 unique 64-bit s
19820 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 igned.** integer
19830 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 key called the
19840 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 [ROWID | "rowid"
19850 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 ]. ^The rowid is
19860 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c always availabl
19870 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 e.** as an undec
19880 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d lared column nam
19890 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f ed ROWID, OID, o
198a0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e r _ROWID_ as lon
198b0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 g as those.** na
198c0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f mes are not also
198d0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 used by explici
198e0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
198f0 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 umns. ^If.** the
19900 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
19910 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 umn of type [INT
19920 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
19930 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 ] then that colu
19940 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 mn.** is another
19950 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 alias for the r
19960 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 owid..**.** ^Thi
19970 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
19980 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
19990 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
199a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
199b0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 INSERT] into the
199c0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 database from t
199d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
199e0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 nection].** in t
199f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
19a00 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 t. ^As of SQLit
19a10 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c e version 3.7.7,
19a20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a this routines.*
19a30 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 * records the la
19a40 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 st insert rowid
19a50 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 of both ordinary
19a60 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 tables and [vir
19a70 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a tual tables]..**
19a80 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 ^If no successf
19a90 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 ul [INSERT]s.**
19aa0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
19ab0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 ed on that datab
19ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
19ad0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
19ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 ..**.** ^(If an
19af0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 [INSERT] occurs
19b00 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
19b10 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 or within a [vi
19b20 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 rtual table].**
19b30 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 method, then thi
19b40 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 s routine will r
19b50 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 eturn the [rowid
19b60 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 ] of the inserte
19b70 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 d.** row as long
19b80 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 as the trigger
19b90 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 or virtual table
19ba0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 method is runni
19bb0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 ng..** But once
19bc0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
19bd0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 irtual table met
19be0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 hod ends, the va
19bf0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a lue returned .**
19c00 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
19c10 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 reverts to what
19c20 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 it was before t
19c30 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
19c40 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d rtual.** table m
19c50 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a ethod began.)^.*
19c60 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 *.** ^An [INSERT
19c70 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 ] that fails due
19c80 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 to a constraint
19c90 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f violation is no
19ca0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 t a.** successfu
19cb0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 l [INSERT] and d
19cc0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
19cd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
19ce0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 d by this.** rou
19cf0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 tine. ^Thus INS
19d00 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 ERT OR FAIL, INS
19d10 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 ERT OR IGNORE, I
19d20 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 NSERT OR ROLLBAC
19d30 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 K,.** and INSERT
19d40 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e OR ABORT make n
19d50 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 o changes to the
19d60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
19d70 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
19d80 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 when their inse
19d90 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 rtion fails. ^(
19da0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
19db0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
19dc0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
19dd0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
19de0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
19df0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
19e00 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
19e10 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
19e20 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
19e30 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
19e40 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
19e50 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
19e60 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
19e70 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
19e80 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
19e90 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e his interface.)^
19ea0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 .**.** ^For the
19eb0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 purposes of this
19ec0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e routine, an [IN
19ed0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 SERT] is conside
19ee0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 red to.** be suc
19ef0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 cessful even if
19f00 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 it is subsequent
19f10 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
19f20 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
19f30 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c ion is accessibl
19f40 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 e to SQL stateme
19f50 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b nts via the.** [
19f60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
19f70 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e d() SQL function
19f80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
19f90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 parate thread pe
19fa0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e rforms a new [IN
19fb0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d SERT] on the sam
19fc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
19fd0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 nnection while t
19fe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
19ff0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
1a000 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
1a010 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 running and thus
1a020 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 changes the las
1a030 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
1a040 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 ,.** then the va
1a050 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1a060 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
1a070 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
1a080 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c .** unpredictabl
1a090 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 e and might not
1a0a0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 equal either the
1a0b0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a old or the new.
1a0c0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b ** last insert [
1a0d0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 rowid]..*/.SQLIT
1a0e0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
1a0f0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
1a100 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
1a110 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1a120 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
1a130 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
1a140 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
1a150 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1a160 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1a170 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
1a180 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
1a190 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 hanged.** or ins
1a1a0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
1a1b0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
1a1c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
1a1d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
1a1e0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
1a1f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
1a200 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
1a210 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
1a220 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 ** ^(Only change
1a230 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
1a240 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
1a250 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b the [INSERT], [
1a260 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b UPDATE],.** or [
1a270 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
1a280 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
1a290 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
1a2a0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
1a2b0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 riggers or [fore
1a2c0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
1a2d0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
1a2e0 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b .)^ Use the.** [
1a2f0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1a300 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
1a310 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f n to find the to
1a320 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
1a330 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 anges.** includi
1a340 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
1a350 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e d by triggers an
1a360 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 d foreign key ac
1a370 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 tions..**.** ^Ch
1a380 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
1a390 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
1a3a0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
1a3b0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
1a3c0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
1a3d0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
1a3e0 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
1a3f0 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ounted..**.** ^(
1a400 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
1a410 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
1a420 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
1a430 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
1a440 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
1a450 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
1a460 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
1a470 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
1a480 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
1a490 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
1a4a0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
1a4b0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
1a4c0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
1a4d0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
1a4e0 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
1a4f0 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
1a500 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
1a510 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
1a520 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e t row changes.)^
1a530 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 .**.** A "trigge
1a540 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 r context" is a
1a550 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 scope of executi
1a560 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 on that begins a
1a570 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 nd.** ends with
1a580 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 the script of a
1a590 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
1a5a0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 | trigger]. .**
1a5b0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 Most SQL stateme
1a5c0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 nts are.** evalu
1a5d0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 ated outside of
1a5e0 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 any trigger. Th
1a5f0 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c is is the "top l
1a600 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 evel".** trigger
1a610 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 context. If a
1a620 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 trigger fires fr
1a630 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
1a640 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 , a.** new trigg
1a650 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e er context is en
1a660 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 tered for the du
1a670 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f ration of that o
1a680 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 ne.** trigger.
1a690 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 Subtriggers crea
1a6a0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 te subcontexts f
1a6b0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f or their duratio
1a6c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e n..**.** ^Callin
1a6d0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
1a6e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
1a6f0 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
1a700 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
1a710 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
1a720 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
1a730 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1a740 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
1a750 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 mber of direct r
1a760 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ow changes in th
1a770 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 e.** most recent
1a780 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
1a790 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
1a7a0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
1a7b0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 same.** trigger
1a7c0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e context..**.** ^
1a7d0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 Thus, when calle
1a7e0 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c d from the top l
1a7f0 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 evel, this funct
1a800 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
1a810 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 ** number of cha
1a820 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
1a830 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
1a840 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
1a850 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f E.** that also o
1a860 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 ccurred at the t
1a870 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 op level. ^(Wit
1a880 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
1a890 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 a trigger,.** th
1a8a0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
1a8b0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 s() interface ca
1a8c0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 n be called to f
1a8d0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
1a8e0 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 f.** changes in
1a8f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
1a900 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
1a910 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
1a920 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
1a930 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f nt within the bo
1a940 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 dy of the same t
1a950 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 rigger..** Howev
1a960 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 er, the number r
1a970 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
1a980 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 include changes
1a990 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 .** caused by su
1a9a0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 btriggers since
1a9b0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 those have their
1a9c0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a own context.)^.
1a9d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
1a9e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 he [sqlite3_tota
1a9f0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 l_changes()] int
1aa00 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
1aa10 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
1aa20 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
1aa30 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
1aa40 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
1aa50 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
1aa60 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
1aa70 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
1aa80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1aa90 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
1aaa0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
1aab0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
1aac0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1aad0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 d.** is unpredic
1aae0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
1aaf0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c aningful..*/.SQL
1ab00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1ab10 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 te3_changes(sqli
1ab20 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1ab30 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 PI3REF: Total Nu
1ab40 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
1ab50 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ified.**.** ^Thi
1ab60 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1ab70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1ab80 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 row changes cau
1ab90 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c sed by [INSERT],
1aba0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 .** [UPDATE] or
1abb0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
1abc0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
1abd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1abe0 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
1abf0 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 ** ^(The count r
1ac00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1ac10 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1ac20 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
1ac30 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 changes.** from
1ac40 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 all [CREATE TRIG
1ac50 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 GER | trigger] c
1ac60 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e ontexts and chan
1ac70 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b ges made by.** [
1ac80 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
1ac90 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a ons]. However,.*
1aca0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 * the count does
1acb0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
1acc0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 nges used to imp
1acd0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d lement [REPLACE]
1ace0 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a constraints,.**
1acf0 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 do rollbacks or
1ad00 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
1ad10 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c g, or [DROP TABL
1ad20 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 E] processing.
1ad30 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 The.** count doe
1ad40 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f s not include ro
1ad50 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 ws of views that
1ad60 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 fire an [INSTEA
1ad70 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a D OF trigger],.*
1ad80 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 * though if the
1ad90 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
1ada0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 er makes changes
1adb0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f of its own, tho
1adc0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 se changes .** a
1add0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a re counted.)^.**
1ade0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f ^The sqlite3_to
1adf0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 tal_changes() fu
1ae00 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 nction counts th
1ae10 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f e changes as soo
1ae20 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 n as.** the stat
1ae30 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 ement that makes
1ae40 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 them is complet
1ae50 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 ed (when the sta
1ae60 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a tement handle.**
1ae70 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 is passed to [s
1ae80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1ae90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
1aea0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 lize()])..**.**
1aeb0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
1aec0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
1aed0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
1aee0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
1aef0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
1af00 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 he [total_change
1af10 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1af20 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
1af30 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
1af40 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
1af50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
1af60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
1af70 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f hile [sqlite3_to
1af80 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
1af90 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
1afa0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
1afb0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 rned is unpredic
1afc0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
1afd0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c aningful..*/.SQL
1afe0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1aff0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1b000 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
1b010 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
1b020 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
1b030 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a unning Query.**.
1b040 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1b050 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
1b060 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
1b070 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
1b080 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
1b090 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
1b0a0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
1b0b0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
1b0c0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
1b0d0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
1b0e0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
1b0f0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
1b100 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
1b110 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
1b120 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
1b130 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
1b140 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
1b150 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
1b160 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
1b170 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
1b180 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
1b190 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
1b1a0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
1b1b0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
1b1c0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
1b1d0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
1b1e0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
1b1f0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
1b200 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
1b210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b220 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
1b230 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
1b240 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
1b250 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b260 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
1b270 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
1b280 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
1b290 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
1b2a0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
1b2b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1b2c0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
1b2d0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
1b2e0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
1b2f0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
1b300 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
1b310 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
1b320 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
1b330 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
1b340 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
1b350 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
1b360 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
1b370 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
1b380 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
1b390 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
1b3a0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
1b3b0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
1b3c0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
1b3d0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
1b3e0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
1b3f0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
1b400 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
1b410 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
1b420 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
1b430 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
1b440 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
1b450 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
1b460 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
1b470 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1b480 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
1b490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b4a0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
1b4b0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
1b4c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1b4d0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1b4e0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
1b4f0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
1b500 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
1b510 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
1b520 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
1b530 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
1b540 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
1b550 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
1b560 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
1b570 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1b580 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
1b590 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1b5a0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
1b5b0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
1b5c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
1b5d0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
1b5e0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
1b5f0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
1b600 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
1b610 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
1b620 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1b630 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
1b640 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
1b650 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
1b660 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
1b670 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
1b680 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
1b690 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1b6a0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1b6b0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
1b6c0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1b6d0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
1b6e0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1b6f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
1b700 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
1b710 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
1b720 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
1b730 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
1b740 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
1b750 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1b760 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
1b770 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
1b780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1b790 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
1b7a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
1b7b0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
1b7c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1b7d0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
1b7e0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
1b7f0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
1b800 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
1b810 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
1b820 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
1b830 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
1b840 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
1b850 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
1b860 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
1b870 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
1b880 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
1b890 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
1b8a0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
1b8b0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
1b8c0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1b8d0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
1b8e0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
1b8f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
1b900 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
1b910 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
1b920 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
1b930 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
1b940 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
1b950 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
1b960 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
1b970 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
1b980 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
1b990 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
1b9a0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
1b9b0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
1b9c0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
1b9d0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
1b9e0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
1b9f0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
1ba00 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
1ba10 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
1ba20 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
1ba30 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
1ba40 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
1ba50 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
1ba60 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
1ba70 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
1ba80 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
1ba90 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
1baa0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
1bab0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
1bac0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
1bad0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
1bae0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1baf0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
1bb00 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
1bb10 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
1bb20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
1bb30 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
1bb40 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1bb50 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
1bb60 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
1bb70 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
1bb80 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
1bb90 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
1bba0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
1bbb0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
1bbc0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
1bbd0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
1bbe0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
1bbf0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
1bc00 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
1bc10 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
1bc20 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
1bc30 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
1bc40 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
1bc50 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
1bc60 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
1bc70 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
1bc80 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
1bc90 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
1bca0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
1bcb0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
1bcc0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
1bcd0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
1bce0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
1bcf0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
1bd00 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
1bd10 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
1bd20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1bd30 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1bd40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1bd50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
1bd60 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
1bd70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
1bd80 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
1bd90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1bda0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
1bdb0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
1bdc0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c te order..*/.SQL
1bdd0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1bde0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
1bdf0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 st char *sql);.S
1be00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1be10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1be20 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
1be30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1be40 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
1be50 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
1be60 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
1be70 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 rors.**.** ^This
1be80 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1be90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1bea0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
1beb0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
1bec0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
1bed0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
1bee0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
1bef0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
1bf00 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
1bf10 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
1bf20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 .** ^If the busy
1bf30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
1bf40 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f L, then [SQLITE_
1bf50 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
1bf60 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
1bf70 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1bf80 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
1bf90 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
1bfa0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 lock. ^If the
1bfb0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a busy callback.**
1bfc0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
1bfd0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1bfe0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1bff0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
1c000 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1c010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1c020 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c o the busy handl
1c030 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 er is a copy of
1c040 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 the void* pointe
1c050 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 r which.** is th
1c060 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1c070 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 to sqlite3_busy
1c080 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 _handler(). ^Th
1c090 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1c0a0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 t to.** the busy
1c0b0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1c0c0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
1c0d0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
1c0e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
1c0f0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
1c100 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
1c110 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
1c120 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
1c130 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
1c140 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
1c150 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
1c160 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
1c170 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
1c180 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
1c190 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1c1a0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 R_BLOCKED] is re
1c1b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 turned..** ^If t
1c1c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1c1d0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1c1e0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
1c1f0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
1c200 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
1c210 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
1c220 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
1c230 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
1c240 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
1c250 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
1c260 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
1c270 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
1c280 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
1c290 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
1c2a0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 ention. ^If SQLi
1c2b0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 te determines th
1c2c0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 at invoking the
1c2d0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 busy.** handler
1c2e0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 could result in
1c2f0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 a deadlock, it w
1c300 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 ill go ahead and
1c310 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1c320 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c BUSY].** or [SQL
1c330 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
1c340 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e D] instead of in
1c350 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 voking the busy
1c360 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 handler..** Cons
1c370 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 ider a scenario
1c380 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 where one proces
1c390 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1c3a0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a ead lock that.**
1c3b0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f it is trying to
1c3c0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 promote to a re
1c3d0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a served lock and.
1c3e0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 ** a second proc
1c3f0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
1c400 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 reserved lock t
1c410 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 hat it is trying
1c420 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
1c430 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c o an exclusive l
1c440 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 ock. The first
1c450 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 process cannot p
1c460 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 roceed.** becaus
1c470 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1c480 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e by the second an
1c490 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f d the second pro
1c4a0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 cess cannot.** p
1c4b0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 roceed because i
1c4c0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
1c4d0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 the first. If b
1c4e0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a oth processes.**
1c4f0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 invoke the busy
1c500 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 handlers, neith
1c510 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 er will make any
1c520 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 progress. Ther
1c530 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 efore,.** SQLite
1c540 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1c550 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 _BUSY] for the f
1c560 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f irst process, ho
1c570 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a ping that this.*
1c580 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 * will induce th
1c590 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
1c5a0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 to release its r
1c5b0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c ead lock and all
1c5c0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 ow.** the second
1c5d0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 process to proc
1c5e0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1c5f0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c default busy cal
1c600 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a lback is NULL..*
1c610 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
1c620 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 E_BUSY] error is
1c630 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 converted to [S
1c640 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
1c650 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c KED].** when SQL
1c660 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 ite is in the mi
1c670 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 ddle of a large
1c680 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 transaction wher
1c690 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 e all the.** cha
1c6a0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 nges will not fi
1c6b0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 t into the in-me
1c6c0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c mory cache. SQL
1c6d0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 ite will.** alre
1c6e0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 ady hold a RESER
1c6f0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 VED lock on the
1c700 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 database file, b
1c710 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 ut it needs.** t
1c720 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c o promote this l
1c730 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 ock to EXCLUSIVE
1c740 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 so that it can
1c750 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 spill cache.** p
1c760 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 ages into the da
1c770 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 tabase file with
1c780 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 out harm to conc
1c790 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 urrent.** reader
1c7a0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e s. ^If it is un
1c7b0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 able to promote
1c7c0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 the lock, then t
1c7d0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 he in-memory.**
1c7e0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 cache will be le
1c7f0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 ft in an inconsi
1c800 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 stent state and
1c810 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 so the error.**
1c820 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 code is promoted
1c830 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 from the relati
1c840 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c vely benign [SQL
1c850 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 ITE_BUSY] to.**
1c860 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 the more severe
1c870 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
1c880 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 OCKED]. ^This e
1c890 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 rror code promot
1c8a0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e ion.** forces an
1c8b0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 automatic rollb
1c8c0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 ack of the chang
1c8d0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 es. See the.**
1c8e0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 <a href="/cvstra
1c8f0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
1c900 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
1c910 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
1c920 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
1c930 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
1c940 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
1c950 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
1c960 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
1c970 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 nt..**.** ^(Ther
1c980 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1c990 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1c9a0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1c9b0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1c9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1c9d0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1c9e0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1c9f0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1ca00 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1ca10 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1ca20 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1ca30 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1ca40 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 ** will also set
1ca50 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 or clear the bu
1ca60 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a sy handler..**.*
1ca70 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 * The busy callb
1ca80 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 ack should not t
1ca90 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 ake any actions
1caa0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 which modify the
1cab0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1cac0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1cad0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
1cae0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 ndler. Any such
1caf0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 actions.** resu
1cb00 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
1cb10 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a behavior..** .**
1cb20 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
1cb30 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
1cb40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1cb50 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
1cb60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1cb70 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
1cb80 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1cb90 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1cba0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
1cbb0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1cbc0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
1cbd0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
1cbe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
1cbf0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
1cc00 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1cc10 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
1cc20 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1cc30 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
1cc40 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
1cc50 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
1cc60 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
1cc70 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
1cc80 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
1cc90 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
1cca0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
1ccb0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
1ccc0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1ccd0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
1cce0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
1ccf0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
1cd00 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1cd10 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1cd20 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
1cd30 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
1cd40 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
1cd50 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
1cd60 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
1cd70 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
1cd80 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
1cd90 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
1cda0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1cdb0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
1cdc0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
1cdd0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
1cde0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
1cdf0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
1ce00 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
1ce10 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
1ce20 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
1ce30 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
1ce40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ce50 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 on] any any give
1ce60 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
1ce70 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1ce80 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
1ce90 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
1cea0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1ceb0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
1cec0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
1ced0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
1cee0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1cef0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 cleared.)^.*/.S
1cf00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1cf10 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1cf20 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
1cf30 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
1cf40 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
1cf50 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
1cf60 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
1cf70 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1cf80 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1cf90 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1cfa0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1cfb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1cfc0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1cfd0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1cfe0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1cff0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1d000 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1d010 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1d020 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1d030 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1d040 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1d050 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1d060 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1d070 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1d080 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1d090 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1d0a0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1d0b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1d0c0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1d0d0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1d0e0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1d0f0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1d100 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1d110 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1d120 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1d130 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1d140 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1d150 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1d160 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1d170 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1d180 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1d190 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1d1a0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1d1b0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1d1c0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1d1d0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1d1e0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1d1f0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1d200 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1d210 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1d220 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1d230 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1d240 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1d250 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1d260 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1d270 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1d280 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1d290 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1d2a0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1d2b0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1d2c0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1d2d0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1d2e0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1d2f0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1d300 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1d310 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1d320 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1d330 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1d340 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1d350 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1d360 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1d370 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1d380 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1d390 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1d3a0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1d3b0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1d3c0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1d3d0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1d3e0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1d3f0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1d400 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1d410 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1d420 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1d430 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1d440 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1d450 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1d460 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1d470 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1d480 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1d490 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1d4a0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1d4b0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1d4c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1d4d0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1d4e0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1d4f0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1d500 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1d510 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1d520 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1d530 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1d540 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1d550 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1d560 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1d570 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1d580 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1d590 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1d5a0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1d5b0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1d5c0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1d5d0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1d5e0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1d5f0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1d600 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1d610 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1d620 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1d630 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1d640 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d650 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1d660 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1d670 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1d680 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1d690 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1d6a0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1d6b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1d6c0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1d6d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1d6e0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1d6f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1d700 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1d710 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1d720 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1d730 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1d740 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1d750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1d760 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1d770 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1d780 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1d790 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1d7a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1d7b0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1d7c0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1d7d0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1d7e0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1d7f0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1d800 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1d810 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1d820 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1d830 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1d840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1d850 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1d860 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1d870 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d880 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1d890 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1d8a0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1d8b0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1d8c0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1d8d0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1d8e0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1d8f0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1d900 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1d910 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1d920 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1d930 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1d940 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1d950 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1d960 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1d970 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1d980 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1d990 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1d9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1d9b0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1d9c0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1d9d0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1d9e0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1d9f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1da00 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1da10 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1da20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1da30 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1da40 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1da50 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1da60 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1da70 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1da80 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1da90 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1daa0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1dab0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1dac0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1dad0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1dae0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1daf0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1db00 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1db10 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1db20 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1db30 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1db40 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1db50 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1db60 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1db70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1db80 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1db90 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1dba0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f g()]..*/.SQLITE_
1dbb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1dbc0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c get_table(. sql
1dbd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1dbe0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
1dbf0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
1dc00 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1dc10 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
1dc20 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 valuated */. ch
1dc30 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c ar ***pazResult,
1dc40 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f /* Results o
1dc50 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 f the query */.
1dc60 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 int *pnRow,
1dc70 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1dc80 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 of result rows
1dc90 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1dca0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c int *pnColumn,
1dcb0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1dcc0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 r of result colu
1dcd0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 mns written here
1dce0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 */. char **pzE
1dcf0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 rrmsg /* E
1dd00 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
1dd10 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 here */.);.SQLI
1dd20 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
1dd30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
1dd40 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
1dd50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1dd60 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
1dd70 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
1dd80 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1dd90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
1dda0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
1ddb0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
1ddc0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
1ddd0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
1dde0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
1ddf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1de00 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
1de10 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1de20 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
1de30 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
1de40 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
1de50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
1de60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
1de70 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
1de80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
1de90 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
1dea0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
1deb0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
1dec0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
1ded0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1dee0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
1def0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
1df00 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
1df10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
1df20 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
1df30 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
1df40 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
1df50 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
1df60 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
1df70 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
1df80 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
1df90 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
1dfa0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
1dfb0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
1dfc0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
1dfd0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
1dfe0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1dff0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
1e000 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
1e010 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
1e020 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
1e030 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
1e040 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
1e050 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
1e060 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
1e070 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 printf().)^ Thi
1e080 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
1e090 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
1e0a0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
1e0b0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
1e0c0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
1e0d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
1e0e0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 ^(Note also th
1e0f0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 at sqlite3_snpri
1e100 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 ntf().** returns
1e110 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
1e120 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 s buffer instead
1e130 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
1e140 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 f.** characters
1e150 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e actually written
1e160 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 into the buffer
1e170 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 .)^ We admit th
1e180 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 at.** the number
1e190 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 of characters w
1e1a0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 ritten would be
1e1b0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 a more useful re
1e1c0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 turn.** value bu
1e1d0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e t we cannot chan
1e1e0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ge the implement
1e1f0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
1e200 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e _snprintf().** n
1e210 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ow without break
1e220 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ing compatibilit
1e230 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e y..**.** ^As lon
1e240 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
1e250 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
1e260 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
1e270 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1e280 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
1e290 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
1e2a0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
1e2b0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 nated. ^The fir
1e2c0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
1e2d0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
1e2e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
1e2f0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
1e300 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
1e310 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1e320 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
1e330 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
1e340 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
1e350 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
1e360 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
1e370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1e380 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 ite3_vsnprintf()
1e390 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 routine is a va
1e3a0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 rargs version of
1e3b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1e3c0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 f()..**.** These
1e3d0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
1e3e0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
1e3f0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
1e400 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
1e410 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
1e420 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
1e430 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
1e440 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
1e450 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
1e460 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
1e470 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
1e480 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
1e490 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
1e4a0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
1e4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 ..**.** ^(The %q
1e4c0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1e4d0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
1e4e0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
1e4f0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
1e500 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
1e510 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
1e520 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
1e530 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
1e540 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
1e550 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
1e560 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
1e570 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
1e580 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
1e590 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
1e5a0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
1e5b0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
1e5c0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
1e5d0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
1e5e0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
1e5f0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1e600 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
1e610 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
1e620 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
1e630 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1e640 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1e650 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1e660 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
1e670 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
1e680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1e690 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
1e6a0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
1e6b0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
1e6c0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
1e6d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1e6e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1e6f0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
1e700 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
1e710 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
1e720 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
1e730 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1e740 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1e750 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1e760 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1e770 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e780 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
1e790 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
1e7a0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
1e7b0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
1e7c0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
1e7d0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
1e7e0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
1e7f0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
1e800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1e810 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
1e820 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
1e830 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
1e840 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
1e850 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1e860 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
1e870 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
1e880 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
1e890 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
1e8a0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
1e8b0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
1e8c0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
1e8d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1e8e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1e8f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1e900 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
1e910 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
1e920 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1e930 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
1e940 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
1e950 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
1e960 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
1e970 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
1e980 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
1e990 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
1e9a0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
1e9b0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
1e9c0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
1e9d0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
1e9e0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
1e9f0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
1ea00 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
1ea10 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
1ea20 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
1ea30 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
1ea40 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
1ea50 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
1ea60 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
1ea70 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
1ea80 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
1ea90 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
1eaa0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
1eab0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
1eac0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
1ead0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
1eae0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
1eaf0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1eb00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1eb10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1eb20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1eb30 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
1eb40 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
1eb50 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
1eb60 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
1eb70 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
1eb80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1eb90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1eba0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
1ebb0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
1ebc0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
1ebd0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
1ebe0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
1ebf0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
1ec00 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
1ec10 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
1ec20 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
1ec30 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
1ec40 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
1ec50 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
1ec60 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
1ec70 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
1ec80 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
1ec90 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
1eca0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
1ecb0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
1ecc0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
1ecd0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 ring.)^.*/.SQLIT
1ece0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
1ecf0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
1ed00 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 t char*,...);.SQ
1ed10 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
1ed20 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1ed30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1ed40 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 list);.SQLITE_AP
1ed50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1ed60 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1ed70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1ed80 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
1ed90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
1eda0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1edb0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1edc0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1edd0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1ede0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1edf0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1ee00 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1ee10 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1ee20 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1ee30 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1ee40 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1ee50 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1ee60 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1ee70 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1ee80 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1ee90 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1eea0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1eeb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1eec0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1eed0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1eee0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1eef0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1ef00 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1ef10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1ef20 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1ef30 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1ef40 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1ef50 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1ef60 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1ef70 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1ef80 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1ef90 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1efa0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1efb0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1efc0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1efd0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1efe0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1eff0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1f000 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1f010 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1f020 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1f030 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1f040 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1f050 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1f060 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
1f070 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 sqlite3_free() w
1f080 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 ith a pointer pr
1f090 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
1f0a0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
1f0b0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
1f0c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
1f0d0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f leases that memo
1f0e0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 ry so.** that it
1f0f0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 might be reused
1f100 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
1f110 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
1f120 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
1f130 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1f140 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
1f150 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
1f160 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
1f170 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
1f180 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
1f190 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
1f1a0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
1f1b0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
1f1c0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
1f1d0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
1f1e0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
1f1f0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
1f200 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
1f210 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
1f220 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
1f230 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
1f240 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
1f250 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
1f260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1f270 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
1f280 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
1f290 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
1f2a0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
1f2b0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
1f2c0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
1f2d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
1f2e0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1f2f0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a realloc()..**.**
1f300 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ^(The sqlite3_r
1f310 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 ealloc() interfa
1f320 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 ce attempts to r
1f330 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 esize a.** prior
1f340 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1f350 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 on to be at leas
1f360 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 t N bytes, where
1f370 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 N is the.** sec
1f380 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
1f390 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 The memory alloc
1f3a0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 ation to be resi
1f3b0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 zed is the first
1f3c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e .** parameter.)^
1f3d0 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 ^ If the first
1f3e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1f3f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
1f400 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
1f410 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
1f420 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
1f430 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
1f440 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f450 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 N) where N is th
1f460 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1f470 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1f480 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 alloc()..** ^If
1f490 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1f4a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1f4b0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 realloc() is zer
1f4c0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 o or.** negative
1f4d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1f4e0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 or is exactly th
1f4f0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e e same as callin
1f500 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 g.** sqlite3_fre
1f510 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 e(P) where P is
1f520 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1f530 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1f540 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 ealloc()..** ^sq
1f550 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1f560 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1f570 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
1f580 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
1f590 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1f5a0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
1f5b0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 if sufficient me
1f5c0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 mory is unavaila
1f5d0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 ble..** ^If M is
1f5e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
1f5f0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f600 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 n, then min(N,M)
1f610 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 bytes.** of the
1f620 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1f630 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 n are copied int
1f640 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
1f650 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e of buffer return
1f660 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1f670 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 _realloc() and t
1f680 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1f690 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1f6a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1f6b0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e lloc() returns N
1f6c0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ULL, then the pr
1f6d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ior allocation.*
1f6e0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a * is not freed..
1f6f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
1f700 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 y returned by sq
1f710 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 lite3_malloc() a
1f720 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c nd sqlite3_reall
1f730 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 oc().** is alway
1f740 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 s aligned to at
1f750 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 least an 8 byte
1f760 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 boundary, or to
1f770 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e a.** 4 byte boun
1f780 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c dary if the [SQL
1f790 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e ITE_4_BYTE_ALIGN
1f7a0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 ED_MALLOC] compi
1f7b0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
1f7c0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n is used..**.**
1f7d0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
1f7e0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
1f7f0 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
1f800 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
1f810 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
1f820 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
1f830 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
1f840 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
1f850 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
1f860 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
1f870 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
1f880 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
1f890 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
1f8a0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
1f8b0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
1f8c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
1f8d0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
1f8e0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
1f8f0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
1f900 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 10, the Windows
1f910 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
1f920 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 er called.** the
1f930 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
1f940 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 and free() dire
1f950 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 ctly when conver
1f960 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ting.** filename
1f970 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 s between the UT
1f980 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 F-8 encoding use
1f990 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 d by SQLite.** a
1f9a0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 nd whatever file
1f9b0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 name encoding is
1f9c0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 used by the par
1f9d0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a ticular Windows.
1f9e0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e ** installation.
1f9f0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 Memory allocat
1fa00 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 ion errors were
1fa10 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
1fa20 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 they were repor
1fa30 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c ted back as [SQL
1fa40 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 ITE_CANTOPEN] or
1fa50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
1fa60 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b R] rather than [
1fa70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
1fa80 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 *.** The pointer
1fa90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 arguments to [s
1faa0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 qlite3_free()] a
1fab0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
1fac0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 loc()].** must b
1fad0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
1fae0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
1faf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
1fb00 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 rior.** invocati
1fb10 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
1fb20 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
1fb30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
1fb40 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 that have.** not
1fb50 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 yet been releas
1fb60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 ed..**.** The ap
1fb70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
1fb80 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 ot read or write
1fb90 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 any part of.**
1fba0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 a block of memor
1fbb0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 y after it has b
1fbc0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 een released usi
1fbd0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
1fbe0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
1fbf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
1fc00 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
1fc10 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
1fc20 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 c(int);.SQLITE_A
1fc30 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
1fc40 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
1fc50 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
1fc60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 void sqlite3_fr
1fc70 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ee(void*);../*.*
1fc80 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
1fc90 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 ry Allocator Sta
1fca0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 tistics.**.** SQ
1fcb0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 Lite provides th
1fcc0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 ese two interfac
1fcd0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 es for reporting
1fce0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a on the status.*
1fcf0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
1fd00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 3_malloc()], [sq
1fd10 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 lite3_free()], a
1fd20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
1fd30 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e loc()].** routin
1fd40 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 es, which form t
1fd50 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f he built-in memo
1fd60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
1fd70 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e bsystem..**.** ^
1fd80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
1fd90 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 ory_used()] rout
1fda0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
1fdb0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a number of bytes.
1fdc0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 ** of memory cur
1fdd0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 rently outstandi
1fde0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 ng (malloced but
1fdf0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 not freed)..**
1fe00 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
1fe10 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1fe20 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
1fe30 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a s the maximum.**
1fe40 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
1fe50 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1fe60 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 ] since the high
1fe70 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 -water mark.** w
1fe80 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 as last reset.
1fe90 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
1fea0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
1feb0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1fec0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1fed0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1fee0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 ()] include any
1fef0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 overhead.** adde
1ff00 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
1ff10 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
1ff20 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
1ff30 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 lloc()],.** but
1ff40 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 not overhead add
1ff50 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e ed by the any un
1ff60 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 derlying system
1ff70 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 library.** routi
1ff80 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 nes that [sqlite
1ff90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 3_malloc()] may
1ffa0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 call..**.** ^The
1ffb0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 memory high-wat
1ffc0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 er mark is reset
1ffd0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 to the current
1ffe0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c value of.** [sql
1fff0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
20000 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 ()] if and only
20010 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
20020 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
20030 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
20040 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 ()] is true. ^T
20050 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
20060 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
20070 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
20080 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 r(1)] is the hig
20090 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
200a0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 prior to the res
200b0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 et..*/.SQLITE_AP
200c0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 I sqlite3_int64
200d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
200e0 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 sed(void);.SQLIT
200f0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
20100 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
20110 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
20120 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
20130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
20140 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
20150 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a er Generator.**.
20160 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 ** SQLite contai
20170 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 ns a high-qualit
20180 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 y pseudo-random
20190 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 number generator
201a0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a (PRNG) used to.
201b0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d ** select random
201c0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 [ROWID | ROWIDs
201d0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 ] when inserting
201e0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 new records int
201f0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a o a table that.*
20200 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 * already uses t
20210 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 he largest possi
20220 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 ble [ROWID]. Th
20230 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 e PRNG is also u
20240 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 sed for.** the b
20250 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 uild-in random()
20260 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 and randomblob(
20270 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e ) SQL functions.
20280 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 This interface
20290 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 allows.** appli
202a0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 cations to acces
202b0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 s the same PRNG
202c0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 for other purpos
202d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c es..**.** ^A cal
202e0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e l to this routin
202f0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 e stores N bytes
20300 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 of randomness i
20310 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a nto buffer P..**
20320 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 .** ^The first t
20330 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ime this routine
20340 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 is invoked (eit
20350 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f her internally o
20360 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c r by.** the appl
20370 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e ication) the PRN
20380 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e G is seeded usin
20390 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
203a0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 ained.** from th
203b0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 e xRandomness me
203c0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
203d0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
203e0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e ] object..** ^On
203f0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 all subsequent
20400 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 invocations, the
20410 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
20420 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a ss is generated.
20430 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e ** internally an
20440 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 d without recour
20450 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 se to the [sqlit
20460 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e e3_vfs] xRandomn
20470 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a ess.** method..*
20480 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
20490 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
204a0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
204b0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
204c0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
204d0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
204e0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a n Callbacks.**.*
204f0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
20500 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 registers an aut
20510 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20520 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c with a particul
20530 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
20540 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 connection], sup
20550 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 plied in the fir
20560 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 st argument..**
20570 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
20580 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
20590 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 ked as SQL state
205a0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 ments are being
205b0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b compiled.** by [
205c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
205d0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
205e0 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ts [sqlite3_prep
205f0 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 are_v2()],.** [s
20600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
20610 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
20620 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
20630 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a . ^At various.*
20640 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 * points during
20650 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 the compilation
20660 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 process, as logi
20670 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 c is being creat
20680 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d ed.** to perform
20690 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 various actions
206a0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 , the authorizer
206b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
206c0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 oked to.** see i
206d0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 f those actions
206e0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 are allowed. ^T
206f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
20700 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
20710 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
20720 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 OK] to allow the
20730 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 action, [SQLITE
20740 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 _IGNORE] to disa
20750 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 llow the.** spec
20760 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 ific action but
20770 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 allow the SQL st
20780 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 atement to conti
20790 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d nue to be.** com
207a0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 piled, or [SQLIT
207b0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 E_DENY] to cause
207c0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 the entire SQL
207d0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a statement to be.
207e0 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 ** rejected with
207f0 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 an error. ^If
20800 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
20810 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
20820 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 ** any value oth
20830 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
20840 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 IGNORE], [SQLITE
20850 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 _OK], or [SQLITE
20860 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 _DENY].** then t
20870 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
20880 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
20890 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
208a0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 t triggered.** t
208b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 he authorizer wi
208c0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
208d0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
208e0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
208f0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
20900 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 SQLITE_OK], that
20910 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 means the opera
20920 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 tion.** requeste
20930 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 d is ok. ^When
20940 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
20950 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e urns [SQLITE_DEN
20960 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 Y], the.** [sqli
20970 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20980 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
20990 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
209a0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f red the.** autho
209b0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
209c0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
209d0 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 ssage explaining
209e0 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 that.** access
209f0 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a is denied. .**.*
20a00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
20a10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
20a20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
20a30 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
20a40 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 he third.** para
20a50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
20a60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
20a70 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e zer() interface.
20a80 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
20a90 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
20aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
20ab0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f integer [SQLITE_
20ac0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f COPY | action co
20ad0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 de] that specifi
20ae0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 es.** the partic
20af0 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 ular action to b
20b00 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 e authorized. ^T
20b10 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 he third through
20b20 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 sixth parameter
20b30 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c s.** to the call
20b40 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 back are zero-te
20b50 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
20b60 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 that contain ad
20b70 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 ditional.** deta
20b80 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 ils about the ac
20b90 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
20ba0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rized..**.** ^If
20bb0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
20bc0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 is [SQLITE_READ
20bd0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c ].** and the cal
20be0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
20bf0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
20c00 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 en the.** [prepa
20c10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 red statement] s
20c20 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 tatement is cons
20c30 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 tructed to subst
20c40 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 itute.** a NULL
20c50 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f value in place o
20c60 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 f the table colu
20c70 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 mn that would ha
20c80 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 ve.** been read
20c90 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 if [SQLITE_OK] h
20ca0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 ad been returned
20cb0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 . The [SQLITE_I
20cc0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e GNORE].** return
20cd0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
20ce0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 deny an untruste
20cf0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f d user access to
20d00 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 individual.** c
20d10 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c olumns of a tabl
20d20 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 e..** ^If the ac
20d30 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
20d40 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
20d50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
20d60 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
20d70 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
20d80 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
20d90 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
20da0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
20db0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
20dc0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
20dd0 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
20de0 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
20df0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
20e00 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
20e10 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
20e20 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
20e30 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
20e40 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
20e50 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
20e60 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
20e70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
20e80 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
20e90 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
20ea0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
20eb0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
20ec0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
20ed0 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
20ee0 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
20ef0 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
20f00 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
20f10 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
20f20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
20f30 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
20f40 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
20f50 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
20f60 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
20f70 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
20f80 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
20f90 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
20fa0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
20fb0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
20fc0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
20fd0 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
20fe0 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
20ff0 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
21000 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
21010 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
21020 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
21030 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
21040 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
21050 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
21060 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
21070 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
21080 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
21090 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
210a0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
210b0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
210c0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
210d0 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
210e0 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
210f0 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
21100 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
21110 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
21120 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
21130 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
21140 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
21150 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
21160 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
21170 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
21180 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 er..**.** ^(Only
21190 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
211a0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
211b0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
211c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
211d0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
211e0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
211f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
21200 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
21210 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
21220 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 )^ ^Disable the
21230 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 authorizer by i
21240 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c nstalling a NULL
21250 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 callback..** Th
21260 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 e authorizer is
21270 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
21280 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ult..**.** The a
21290 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
212a0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
212b0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
212c0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
212d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
212e0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
212f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21300 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 callback..** Not
21310 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
21320 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
21330 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
21340 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
21350 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
21360 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
21370 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
21380 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
21390 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
213a0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 * ^When [sqlite3
213b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
213c0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
213d0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
213e0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
213f0 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 might be re-prep
21400 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c ared during [sql
21410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 ite3_step()] due
21420 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 to a .** schema
21430 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c change. Hence,
21440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
21450 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 should ensure t
21460 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 hat the.** corre
21470 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ct authorizer ca
21480 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 llback remains i
21490 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 n place during t
214a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
214b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ()]..**.** ^Note
214c0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
214d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
214e0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 invoked only du
214f0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ring.** [sqlite3
21500 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
21510 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
21520 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
21530 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
21540 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
21550 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
21560 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
21570 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 unless.** as st
21580 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 ated in the prev
21590 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 ious paragraph,
215a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
215b0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 nvokes.** sqlite
215c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 3_prepare_v2() t
215d0 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 o reprepare a st
215e0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 atement after a
215f0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a schema change..*
21600 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
21610 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
21620 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 horizer(. sqlit
21630 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 e3*,. int (*xAu
21640 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f th)(void*,int,co
21650 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
21660 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
21670 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a *,const char*),.
21680 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
21690 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a.);../*.** CAPI
216a0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
216b0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a Return Codes.**
216c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
216d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
216e0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
216f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 lback function]
21700 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 must.** return e
21710 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b ither [SQLITE_OK
21720 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] or one of thes
21730 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 e two constants
21740 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 in order.** to s
21750 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 ignal SQLite whe
21760 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
21770 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 action is permit
21780 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ted. See the.**
21790 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
217a0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
217b0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 rizer documentat
217c0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f ion] for additio
217d0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
217e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 on..**.** Note t
217f0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 hat SQLITE_IGNOR
21800 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 E is also used a
21810 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c s a [SQLITE_ROLL
21820 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f BACK | return co
21830 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 de].** from the
21840 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
21850 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 _conflict()] int
21860 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
21870 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
21880 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
21890 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
218a0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
218b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
218c0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
218d0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
218e0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
218f0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
21900 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21910 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
21920 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
21930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
21940 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
21950 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
21960 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
21970 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
21980 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
21990 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
219a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
219b0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
219c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
219d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
219e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
219f0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
21a00 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
21a10 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
21a20 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
21a30 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
21a40 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
21a50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
21a60 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
21a70 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
21a80 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
21a90 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
21aa0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
21ab0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
21ac0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
21ad0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
21ae0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
21af0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
21b00 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
21b10 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
21b20 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
21b30 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
21b40 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
21b50 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
21b60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
21b70 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 ter. ^(The 5th
21b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
21b90 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
21ba0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
21bb0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
21bc0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
21bd0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
21be0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 applicable.)^
21bf0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 ^The 6th paramet
21c00 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
21c10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
21c20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
21c30 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
21c40 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
21c50 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
21c60 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
21c70 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
21c80 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
21c90 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
21ca0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 irectly from.**
21cb0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
21cc0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
21cd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21ce0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21cf0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
21d00 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
21d10 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
21d20 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
21d30 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
21d40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
21d50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
21d60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21d70 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
21d80 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
21d90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
21da0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21dc0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
21dd0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
21de0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
21df0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
21e00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21e10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
21e20 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
21e30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
21e40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
21e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21e60 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
21e70 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
21e80 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
21e90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
21ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21eb0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
21ec0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
21ed0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
21ee0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
21ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21f00 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
21f10 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
21f20 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
21f30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
21f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
21f50 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
21f60 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
21f70 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
21f80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
21fa0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
21fb0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
21fc0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
21fd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
21fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
21ff0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
22000 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
22010 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
22020 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
22030 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
22040 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
22050 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
22060 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22070 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22080 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
22090 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
220a0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
220b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
220c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
220d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
220e0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
220f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22100 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22110 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22120 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
22130 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
22140 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
22150 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
22160 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22170 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
22180 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
22190 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
221a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
221b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
221c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
221d0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
221e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
221f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
22200 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22210 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
22220 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
22230 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
22240 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22250 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22260 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
22270 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
22280 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22290 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
222a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
222b0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
222c0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
222d0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
222e0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
222f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22300 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
22310 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
22320 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
22330 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
22340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22350 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
22360 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
22370 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
22380 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
223a0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
223b0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 22 /* Ope
223c0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c ration NUL
223d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
223e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
223f0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
22400 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
22410 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
22420 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
22430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
22440 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
22450 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
22460 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
22470 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
22490 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
224a0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
224b0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
224c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
224d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
224e0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
224f0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
22500 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
22510 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
22520 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
22530 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
22540 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
22550 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
22560 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22570 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
22580 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
22590 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
225a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
225b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
225c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
225d0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
225e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
225f0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
22600 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
22610 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
22620 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
22630 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22640 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
22650 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22660 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
22670 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
22680 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
22690 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d Function Nam
226a0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 e */.#define S
226b0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 QLITE_SAVEPOINT
226c0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 32
226d0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
226e0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d Savepoint Nam
226f0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e */.#define SQ
22700 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
22710 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
22720 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
22730 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
22740 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
22750 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
22760 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
22770 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
22780 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
22790 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
227a0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
227b0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
227c0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
227d0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
227e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
227f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
22800 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
22810 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22820 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
22830 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
22840 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
22850 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
22860 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
22870 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
22880 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
22890 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
228a0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
228b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
228c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
228d0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
228e0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
228f0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
22900 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
22910 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
22920 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
22930 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
22940 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
22950 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
22960 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
22970 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
22980 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
22990 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
229a0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
229b0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
229c0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 * ^The callback
229d0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
229e0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
229f0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
22a00 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
22a10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
22a20 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f ishes. ^The pro
22a30 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f file callback co
22a40 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 ntains.** the or
22a50 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
22a60 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 text and an est
22a70 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c imate of wall-cl
22a80 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 ock time.** of h
22a90 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 ow long that sta
22aa0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 tement took to r
22ab0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c un. ^The profil
22ac0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 e callback.** ti
22ad0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f me is in units o
22ae0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 f nanoseconds, h
22af0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 owever the curre
22b00 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
22b10 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 n.** is only cap
22b20 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 able of millisec
22b30 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 ond resolution s
22b40 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 o the six least
22b50 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 significant.** d
22b60 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d igits in the tim
22b70 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 e are meaningles
22b80 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 s. Future versi
22b90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ons of SQLite.**
22ba0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 might provide g
22bb0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f reater resolutio
22bc0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 n on the profile
22bd0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 r callback. The
22be0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 .** sqlite3_prof
22bf0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ile() function i
22c00 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 s considered exp
22c10 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
22c20 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 .** subject to c
22c30 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 hange in future
22c40 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
22c50 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 te..*/.SQLITE_AP
22c60 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
22c70 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 trace(sqlite3*,
22c80 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f void(*xTrace)(vo
22c90 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 id*,const char*)
22ca0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 , void*);.SQLITE
22cb0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 _API SQLITE_EXPE
22cc0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
22cd0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
22ce0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
22cf0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
22d00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
22d10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
22d20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
22d30 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
22d40 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
22d50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
22d60 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
22d70 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
22d80 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
22d90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
22da0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
22db0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
22dc0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
22dd0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
22de0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
22df0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
22e00 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
22e10 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
22e20 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
22e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
22e40 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
22e50 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
22e60 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
22e70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
22e80 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
22e90 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
22ea0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
22eb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
22ec0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
22ed0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
22ee0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
22ef0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
22f00 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d ter N is the num
22f10 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 ber of .** [virt
22f20 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 ual machine inst
22f30 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 ructions] that a
22f40 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 re evaluated bet
22f50 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a ween successive.
22f60 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
22f70 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 f the callback X
22f80 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 ..**.** ^Only a
22f90 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 single progress
22fa0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 handler may be d
22fb0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 efined at one ti
22fc0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 me per.** [datab
22fd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b ase connection];
22fe0 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 setting a new p
22ff0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
23000 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f cancels the.** o
23010 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e ld one. ^Settin
23020 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f g parameter X to
23030 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 NULL disables t
23040 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
23050 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f ler..** ^The pro
23060 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 gress handler is
23070 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 also disabled b
23080 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 y setting N to a
23090 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 value less.** t
230a0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 han 1..**.** ^If
230b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 the progress ca
230c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
230d0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 on-zero, the ope
230e0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 ration is.** int
230f0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 errupted. This
23100 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 feature can be u
23110 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
23120 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 a.** "Cancel" b
23130 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 utton on a GUI p
23140 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 rogress dialog b
23150 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ox..**.** The pr
23160 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 ogress handler c
23170 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 allback must not
23180 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
23190 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
231a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
231b0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
231c0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 voked the progre
231d0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e ss handler..** N
231e0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
231f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
23200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
23210 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
23220 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
23230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
23240 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
23250 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
23260 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
23270 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
23280 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 oid sqlite3_prog
23290 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c ress_handler(sql
232a0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 ite3*, int, int(
232b0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
232c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
232d0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 EF: Opening A Ne
232e0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 w Database Conne
232f0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
23300 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e se routines open
23310 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 an SQLite datab
23320 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 ase file as spec
23330 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a ified by the .**
23340 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
23350 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d nt. ^The filenam
23360 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
23370 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
23380 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 -8 for.** sqlite
23390 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
233a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 ite3_open_v2() a
233b0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 nd as UTF-16 in
233c0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a the native byte.
233d0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c ** order for sql
233e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e ite3_open16(). ^
233f0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e (A [database con
23400 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
23410 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
23420 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
23430 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
23440 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
23450 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
23460 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
23470 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
23480 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
23490 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
234a0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
234b0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
234c0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
234d0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
234e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
234f0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
23500 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 ct.)^ ^(If the d
23510 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
23520 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 d (and/or create
23530 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c d) successfully,
23540 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 then.** [SQLITE
23550 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
23560 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
23570 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
23580 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 returned.)^ ^The
23590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
235a0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
235b0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
235c0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
235d0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
235e0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
235f0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
23600 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f of the error fo
23610 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 llowing a failur
23620 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 e of any.** of t
23630 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 he sqlite3_open(
23640 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a ) routines..**.*
23650 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 * ^The default e
23660 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 ncoding for the
23670 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
23680 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c UTF-8 if.** sql
23690 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
236a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
236b0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a is called and.*
236c0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 * UTF-16 in the
236d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
236e0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 r if sqlite3_ope
236f0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a n16() is used..*
23700 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
23710 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
23720 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
23730 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
23740 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
23750 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
23760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
23770 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 ndle should be r
23780 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 eleased by.** pa
23790 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
237a0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 ite3_close()] wh
237b0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 en it is no long
237c0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a er required..**.
237d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f ** The sqlite3_o
237e0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 pen_v2() interfa
237f0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 ce works like sq
23800 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 lite3_open().**
23810 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
23820 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 ccepts two addit
23830 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 ional parameters
23840 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
23850 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 control.** over
23860 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
23870 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 connection. ^(
23880 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
23890 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 ter to.** sqlite
238a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 3_open_v2() can
238b0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 take one of.** t
238c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
238d0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f ee values, optio
238e0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
238f0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
23900 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
23910 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
23920 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c FULLMUTEX], [SQL
23930 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
23940 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ACHE],.** [SQLIT
23950 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
23960 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 CHE], and/or [SQ
23970 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
23980 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 lags:)^.**.** <d
23990 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c l>.** ^(<dt>[SQL
239a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
239b0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 Y]</dt>.** <dd>T
239c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
239d0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e pened in read-on
239e0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ly mode. If the
239f0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e database does n
23a00 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 ot.** already ex
23a10 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 ist, an error is
23a20 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
23a30 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
23a40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
23a50 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 RITE]</dt>.** <d
23a60 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
23a70 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
23a80 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
23a90 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 if possible, or
23aa0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 reading.** only
23ab0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 if the file is
23ac0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 write protected
23ad0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 by the operating
23ae0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 system. In eit
23af0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 her.** case the
23b00 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c database must al
23b10 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 ready exist, oth
23b20 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 erwise an error
23b30 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
23b40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
23b50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
23b60 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
23b70 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f E_OPEN_CREATE]</
23b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
23b90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
23ba0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
23bb0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 d writing, and i
23bc0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 s created if.**
23bd0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 it does not alre
23be0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 ady exist. This
23bf0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 is the behavior
23c00 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
23c10 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 sed for.** sqlit
23c20 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
23c30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c lite3_open16().<
23c40 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
23c50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 **.** If the 3rd
23c60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
23c70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
23c80 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
23c90 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e e.** combination
23ca0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 s shown above op
23cb0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
23cc0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 d with other.**
23cd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
23ce0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f DONLY | SQLITE_O
23cf0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 PEN_* bits].** t
23d00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
23d10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
23d20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 *.** ^If the [SQ
23d30 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
23d40 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 X] flag is set,
23d50 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
23d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
23d70 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c opens in the mul
23d80 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
23d90 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f ding mode] as lo
23da0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 ng as the single
23db0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 -thread.** mode
23dc0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 has not been set
23dd0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
23de0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 or start-time.
23df0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
23e00 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
23e10 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 EX] flag is set
23e20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
23e30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
23e40 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 ns.** in the ser
23e50 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
23e60 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 ng mode] unless
23e70 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 single-thread wa
23e80 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 s.** previously
23e90 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 selected at comp
23ea0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
23eb0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 t-time..** ^The
23ec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
23ed0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 REDCACHE] flag c
23ee0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
23ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
23f00 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 be.** eligible
23f10 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 to use [shared c
23f20 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 ache mode], rega
23f30 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
23f40 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a r or not shared.
23f50 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ** cache is enab
23f60 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 led using [sqlit
23f70 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
23f80 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 _cache()]. ^The
23f90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
23fa0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 _PRIVATECACHE] f
23fb0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
23fc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23fd0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 on to not.** par
23fe0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 ticipate in [sha
23ff0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 red cache mode]
24000 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e even if it is en
24010 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 abled..**.** ^Th
24020 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
24030 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
24040 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
24050 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
24060 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
24070 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
24080 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
24090 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
240a0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 hat.** the new d
240b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
240c0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
240d0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 ^If the fourth p
240e0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
240f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
24100 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
24110 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
24120 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
24130 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
24140 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a ame is ":memory:
24150 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 ", then a privat
24160 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d e, temporary in-
24170 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a memory database.
24180 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f ** is created fo
24190 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
241a0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f . ^This in-memo
241b0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c ry database will
241c0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 vanish when.**
241d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
241e0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
241f0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 d. Future versi
24200 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
24210 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 ght.** make use
24220 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 of additional sp
24230 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 ecial filenames
24240 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 that begin with
24250 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 the ":" characte
24260 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f r..** It is reco
24270 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 mmended that whe
24280 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
24290 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 ename actually d
242a0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a oes begin with.*
242b0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 * a ":" characte
242c0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 r you should pre
242d0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 fix the filename
242e0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 with a pathname
242f0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 such as.** "./"
24300 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 to avoid ambigu
24310 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ity..**.** ^If t
24320 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 he filename is a
24330 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
24340 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
24350 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d temporary.** on-
24360 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 disk database wi
24370 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 ll be created.
24380 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 ^This private da
24390 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a tabase will be.*
243a0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
243b0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 deleted as soon
243c0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 as the database
243d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
243e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 osed..**.** [[UR
243f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 I filenames in s
24400 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 qlite3_open()]]
24410 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 <h3>URI Filename
24420 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 s</h3>.**.** ^If
24430 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 [URI filename]
24440 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
24450 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 s enabled, and t
24460 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
24470 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 ment.** begins w
24480 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 ith "file:", the
24490 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 n the filename i
244a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
244b0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 a URI. ^URI.**
244c0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
244d0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
244e0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ed if the [SQLIT
244f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
24500 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 is.** set in th
24510 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
24520 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 t to sqlite3_ope
24530 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 n_v2(), or if it
24540 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 has.** been ena
24550 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 bled globally us
24560 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
24570 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 CONFIG_URI] opti
24580 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b on with the.** [
24590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
245a0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 ] method or by t
245b0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 he [SQLITE_USE_U
245c0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 RI] compile-time
245d0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f option..** As o
245e0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
245f0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 3.7.7, URI file
24600 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 name interpretat
24610 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 ion is turned of
24620 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c f.** by default,
24630 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 but future rele
24640 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ases of SQLite m
24650 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 ight enable URI
24660 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 filename.** inte
24670 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 rpretation by de
24680 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 fault. See "[UR
24690 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f I filenames]" fo
246a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
246b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
246c0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 ** URI filenames
246d0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f are parsed acco
246e0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 rding to RFC 398
246f0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6. ^If the URI c
24700 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 ontains an.** au
24710 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 thority, then it
24720 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
24730 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
24740 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a or the string .*
24750 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e * "localhost". ^
24760 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 If the authority
24770 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 is not an empty
24780 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 string or "loca
24790 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 lhost", an .** e
247a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
247b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 to the caller.
247c0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f ^The fragment co
247d0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
247e0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 , if .** present
247f0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a , is ignored..**
24800 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
24810 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e the path compon
24820 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 ent of the URI a
24830 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
24840 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 e disk file.** w
24850 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 hich contains th
24860 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 e database. ^If
24870 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 the path begins
24880 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 with a '/' chara
24890 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 cter, .** then i
248a0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
248b0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 as an absolute
248c0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 path. ^If the pa
248d0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 th does not begi
248e0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 n .** with a '/'
248f0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 (meaning that t
24900 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 he authority sec
24910 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 tion is omitted
24920 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a from the URI).**
24930 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 then the path i
24940 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
24950 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
24960 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 . .** ^On window
24970 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d s, the first com
24980 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 ponent of an abs
24990 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 olute path .** i
249a0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 s a drive specif
249b0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 ication (e.g. "C
249c0 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 :")..**.** [[cor
249d0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 e URI query para
249e0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 meters]].** The
249f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
24a00 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e of a URI may con
24a10 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 tain parameters
24a20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 that are interpr
24a30 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 eted.** either b
24a40 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c y SQLite itself,
24a50 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 or by a [VFS |
24a60 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 custom VFS imple
24a70 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 mentation]..** S
24a80 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 QLite interprets
24a90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
24aa0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d hree query param
24ab0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c eters:.**.** <ul
24ac0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 >.** <li> <b>v
24ad0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 fs</b>: ^The "vf
24ae0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 s" parameter may
24af0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 be used to spec
24b00 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a ify the name of.
24b10 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a ** a VFS obj
24b20 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 ect that provide
24b30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
24b40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
24b50 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 that should.**
24b60 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 be used to a
24b70 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
24b80 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e se file on disk.
24b90 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e ^If this option
24ba0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 is set to.**
24bb0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e an empty strin
24bc0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 g the default VF
24bd0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 S object is used
24be0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e . ^Specifying an
24bf0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 unknown.**
24c00 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e VFS is an error.
24c10 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
24c20 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
24c30 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f nd the vfs optio
24c40 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 n is.** pres
24c50 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 ent, then the VF
24c60 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 S specified by t
24c70 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 he option takes
24c80 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a precedence over.
24c90 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 ** the value
24ca0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
24cb0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
24cc0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
24cd0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
24ce0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 i> <b>mode</b>:
24cf0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d ^(The mode param
24d00 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
24d10 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 to either "ro",
24d20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 "rw",.** "rw
24d30 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e c", or "memory".
24d40 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 Attempting to s
24d50 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 et it to any oth
24d60 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 er value is.**
24d70 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a an error)^. .
24d80 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 ** ^If "ro"
24d90 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 is specified, th
24da0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
24db0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
24dc0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 ad-only .**
24dd0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 access, just as
24de0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
24df0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c PEN_READONLY] fl
24e00 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 ag had been set
24e10 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 in the .** t
24e20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
24e30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24e40 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 (). ^If the mode
24e50 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 option is set t
24e60 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 o .** "rw",
24e70 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
24e80 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 e is opened for
24e90 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 read-write (but
24ea0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 not create) .**
24eb0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 access, as i
24ec0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 f SQLITE_OPEN_RE
24ed0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 ADWRITE (but not
24ee0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
24ef0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 ATE) had .**
24f00 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 been set. ^Valu
24f10 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 e "rwc" is equiv
24f20 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
24f30 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 both .** SQ
24f40 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
24f50 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f ITE and SQLITE_O
24f60 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 PEN_CREATE. ^If
24f70 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e the mode option
24f80 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 is.** set t
24f90 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 o "memory" then
24fa0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 a pure [in-memor
24fb0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 y database] that
24fc0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 never reads.**
24fd0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 or writes fr
24fe0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e om disk is used.
24ff0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 ^It is an error
25000 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 to specify a va
25010 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 lue for.** t
25020 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
25030 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 r that is less r
25040 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 estrictive than
25050 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 that specified b
25060 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 y.** the fla
25070 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 gs passed in the
25080 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
25090 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
250a0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
250b0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e li> <b>cache</b>
250c0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 : ^The cache par
250d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 ameter may be se
250e0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 t to either "sha
250f0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 red" or.** "
25100 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 private". ^Setti
25110 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 ng it to "shared
25120 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
25130 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a to setting the.*
25140 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
25150 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 N_SHAREDCACHE bi
25160 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 t in the flags a
25170 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 rgument passed t
25180 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 o.** sqlite3
25190 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 _open_v2(). ^Set
251a0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 ting the cache p
251b0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 arameter to "pri
251c0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 vate" is .**
251d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
251e0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 etting the SQLIT
251f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
25200 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 CHE bit..**
25210 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
25220 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
25230 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 d the "cache" pa
25240 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 rameter is prese
25250 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 nt in.** a U
25260 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 RI filename, its
25270 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 value overrides
25280 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 any behaviour r
25290 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 equested by sett
252a0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 ing.** SQLIT
252b0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
252c0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 CHE or SQLITE_OP
252d0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 EN_SHAREDCACHE f
252e0 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a lag..** </ul>.**
252f0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 .** ^Specifying
25300 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d an unknown param
25310 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 eter in the quer
25320 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
25330 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a URI is not an.*
25340 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 * error. Future
25350 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
25360 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 ite might unders
25370 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 tand additional
25380 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
25390 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 ers. See "[quer
253a0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 y parameters wit
253b0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e h special meanin
253c0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f g to SQLite]" fo
253d0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 r.** additional
253e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
253f0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
25400 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 e examples]] <h3
25410 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 >URI filename ex
25420 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a amples</h3>.**.*
25430 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
25440 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 "1" align=center
25450 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a cellpadding=5>.
25460 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 ** <tr><th> URI
25470 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 filenames <th> R
25480 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 esults.** <tr><t
25490 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 d> file:data.db
254a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
254b0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 Open the file
254c0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
254d0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
254e0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ry..** <tr><td>
254f0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
25500 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 data.db<br>.**
25510 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
25520 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
25530 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 b <br> .**
25540 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c file://local
25550 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 host/home/fred/d
25560 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e ata.db <br> <td>
25570 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
25580 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
25590 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
255a0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 /data.db"..** <t
255b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 r><td> file://da
255c0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 rkstar/home/fred
255d0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a /data.db <td> .*
255e0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
255f0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 ror. "darkstar"
25600 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 is not a recogni
25610 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a zed authority..*
25620 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d * <tr><td style=
25630 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 "white-space:now
25640 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 rap"> .**
25650 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f file:///C:/Do
25660 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 cuments%20and%20
25670 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 Settings/fred/De
25680 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a sktop/data.db.**
25690 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 <td> Window
256a0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 s only: Open the
256b0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
256c0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f on fred's deskto
256d0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 p on drive.**
256e0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 C:. Note
256f0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 that the %20 esc
25700 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 aping in this ex
25710 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 ample is not str
25720 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 ictly .**
25730 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 necessary - s
25740 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 pace characters
25750 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 can be used lite
25760 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 rally.**
25770 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d in URI filenam
25780 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 es..** <tr><td>
25790 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
257a0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 e=ro&cache=priva
257b0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 te <td> .**
257c0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 Open file "
257d0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
257e0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
257f0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 y for read-only
25800 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 access..**
25810 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f Regardless o
25820 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
25830 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f shared-cache mo
25840 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 de is enabled by
25850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 .** def
25860 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 ault, use a priv
25870 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 ate cache..** <t
25880 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d r><td> file:/hom
25890 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 e/fred/data.db?v
258a0 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c fs=unix-nolock <
258b0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 td>.**
258c0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 Open file "/home
258d0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 /fred/data.db".
258e0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 Use the special
258f0 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b VFS "unix-nolock
25900 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 "..** <tr><td> f
25910 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
25920 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a =readonly <td> .
25930 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
25940 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 rror. "readonly"
25950 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 is not a valid
25960 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 option for the "
25970 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e mode" parameter.
25980 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a .** </table>.**.
25990 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 ** ^URI hexadeci
259a0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
259b0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 nces (%HH) are s
259c0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 upported within
259d0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 the path and.**
259e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 query components
259f0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 of a URI. A hex
25a00 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
25a10 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 sequence consist
25a20 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e s of a.** percen
25a30 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 t sign - "%" - f
25a40 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 ollowed by exact
25a50 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d ly two hexadecim
25a60 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 al digits .** sp
25a70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 ecifying an octe
25a80 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 t value. ^Before
25a90 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 the path or que
25aa0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
25ab0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 a.** URI filena
25ac0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 me are interpret
25ad0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 ed, they are enc
25ae0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 oded using UTF-8
25af0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 and all .** hex
25b00 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 adecimal escape
25b10 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 sequences replac
25b20 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 ed by a single b
25b30 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 yte containing t
25b40 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 he.** correspond
25b50 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 ing octet. If th
25b60 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 is process gener
25b70 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 ates an invalid
25b80 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a UTF-8 encoding,.
25b90 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ** the results a
25ba0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
25bb0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 .** <b>Note to W
25bc0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 indows users:</b
25bd0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 > The encoding
25be0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c used for the fil
25bf0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a ename argument.*
25c00 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 * of sqlite3_ope
25c10 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
25c20 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 open_v2() must b
25c30 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 e UTF-8, not wha
25c40 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 tever.** codepag
25c50 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 e is currently d
25c60 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d efined. Filenam
25c70 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e es containing in
25c80 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 ternational.** c
25c90 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 haracters must b
25ca0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 e converted to U
25cb0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 TF-8 prior to pa
25cc0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a ssing them into.
25cd0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
25ce0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
25cf0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 n_v2()..**.** <b
25d00 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
25d10 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c Runtime users:<
25d20 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 /b> The tempora
25d30 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 ry directory mus
25d40 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f t be set.** prio
25d50 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c r to calling sql
25d60 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
25d70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25d80 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 . Otherwise, va
25d90 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 rious.** feature
25da0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 s that require t
25db0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 he use of tempor
25dc0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 ary files may fa
25dd0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c il..**.** See al
25de0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d so: [sqlite3_tem
25df0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a p_directory].*/.
25e00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
25e10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
25e20 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
25e30 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
25e40 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
25e50 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
25e60 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
25e70 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
25e80 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
25e90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
25ea0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 qlite3_open16(.
25eb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c const void *fil
25ec0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
25ed0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
25ee0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 TF-16) */. sqli
25ef0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
25f00 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
25f10 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
25f20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
25f30 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 t sqlite3_open_v
25f40 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2(. const char
25f50 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
25f60 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
25f70 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 e (UTF-8) */. s
25f80 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 qlite3 **ppDb,
25f90 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 /* OUT: S
25fa0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 QLite db handle
25fb0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 */. int flags,
25fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
25fd0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 Flags */. const
25fe0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 char *zVfs
25ff0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 /* Name of VF
26000 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 S module to use
26010 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
26020 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 I3REF: Obtain Va
26030 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 lues For URI Par
26040 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 ameters.**.** Th
26050 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 ese are utility
26060 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c routines, useful
26070 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e to VFS implemen
26080 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 tations, that ch
26090 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 eck.** to see if
260a0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
260b0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 was a URI that
260c0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 contained a spec
260d0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 ific query .** p
260e0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 arameter, and if
260f0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 so obtains the
26100 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 value of that qu
26110 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ery parameter..*
26120 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 *.** If F is the
26130 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
26140 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 me pointer passe
26150 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
26160 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a () method of .**
26170 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 a VFS implement
26180 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 ation when the f
26190 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
261a0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e o xOpen() has on
261b0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 e or .** more of
261c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
261d0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 N_URI] or [SQLIT
261e0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 E_OPEN_MAIN_DB]
261f0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 bits set and.**
26200 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 P is the name of
26210 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d the query param
26220 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 eter, then.** sq
26230 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
26240 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
26250 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
26260 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 e P.** parameter
26270 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 if it exists or
26280 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
26290 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 if P does not ap
262a0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 pear as a .** qu
262b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e ery parameter on
262c0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 F. If P is a q
262d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
262e0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 f F.** has no ex
262f0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 plicit value, th
26300 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
26310 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
26320 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 turns.** a point
26330 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 er to an empty s
26340 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
26350 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
26360 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
26370 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ine assumes that
26380 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a P is a boolean.
26390 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 ** parameter and
263a0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
263b0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 ) or false (0) a
263c0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 ccording to the
263d0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 value.** of P.
263e0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
263f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
26400 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
26410 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a rue (1) if the.*
26420 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 * value of query
26430 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
26440 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 one of "yes", "t
26450 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e rue", or "on" in
26460 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 any.** case or
26470 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
26480 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a ins with a non-z
26490 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 ero number. The
264a0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 .** sqlite3_uri
264b0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
264c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 routines returns
264d0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 false (0) if th
264e0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 e value of.** qu
264f0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
26500 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 is one of "no",
26510 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 "false", or "off
26520 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 " in any case or
26530 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 .** if the value
26540 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
26550 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 umeric zero. If
26560 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 P is not a quer
26570 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
26580 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 n F or if the va
26590 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 lue of P is does
265a0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f not match any o
265b0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 f the.** above,
265c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 then sqlite3_uri
265d0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
265e0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a returns (B!=0)..
265f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26600 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 3_uri_int64(F,P,
26610 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 D) routine conve
26620 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rts the value of
26630 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d P into a.** 64-
26640 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
26650 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 er and returns t
26660 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 hat integer, or
26670 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a D if P does not.
26680 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 ** exist. If th
26690 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
266a0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
266b0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c than an integer,
266c0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 then.** zero is
266d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a returned..** .*
266e0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c * If F is a NULL
266f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 pointer, then s
26700 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
26710 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
26720 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 s NULL and.** sq
26730 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
26740 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
26750 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 B. If F is not
26760 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
26770 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 and.** is not a
26780 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 database file pa
26790 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 thname pointer t
267a0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 hat SQLite passe
267b0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e d into the xOpen
267c0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 .** VFS method,
267d0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
267e0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e r of this routin
267f0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 e is undefined a
26800 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 nd probably.** u
26810 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 ndesirable..*/.S
26820 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
26830 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 char *sqlite3_ur
26840 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 i_parameter(cons
26850 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d t char *zFilenam
26860 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
26870 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 Param);.SQLITE_A
26880 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 PI int sqlite3_u
26890 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 ri_boolean(const
268a0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f char *zFile, co
268b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
268c0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b , int bDefault);
268d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
268e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
268f0 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 3_uri_int64(cons
26900 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 t char*, const c
26910 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e har*, sqlite3_in
26920 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t64);.../*.** CA
26930 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f PI3REF: Error Co
26940 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 des And Messages
26950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26960 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e te3_errcode() in
26970 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
26980 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 the numeric [res
26990 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ult code] or.**
269a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
269b0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d code] for the m
269c0 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 ost recent faile
269d0 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 d sqlite3_* API
269e0 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 call.** associat
269f0 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ed with a [datab
26a00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
26a10 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 If a prior API
26a20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 call failed.** b
26a30 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ut the most rece
26a40 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 nt API call succ
26a50 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 eeded, the retur
26a60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 n value from.**
26a70 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
26a80 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
26a90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
26aa0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
26ab0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
26ac0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
26ad0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
26ae0 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
26af0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
26b00 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
26b10 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
26b20 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
26b30 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
26b40 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
26b50 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
26b60 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
26b70 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
26b80 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
26b90 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
26ba0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
26bb0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
26bc0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
26bd0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
26be0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
26bf0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
26c00 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
26c10 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
26c20 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
26c30 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
26c40 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
26c50 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
26c60 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
26c70 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
26c80 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
26c90 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
26ca0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
26cb0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
26cc0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
26cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
26ce0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
26cf0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
26d00 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
26d10 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
26d20 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
26d30 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
26d40 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
26d50 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
26d60 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
26d70 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
26d80 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
26d90 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
26da0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
26db0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
26dc0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
26dd0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
26de0 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
26df0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
26e00 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
26e10 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
26e20 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
26e30 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
26e40 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
26e50 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
26e60 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
26e70 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
26e80 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
26e90 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
26ea0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
26eb0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
26ec0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
26ed0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
26ee0 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
26ef0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
26f00 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
26f10 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
26f20 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
26f30 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
26f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26f50 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
26f60 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
26f70 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
26f80 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
26f90 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
26fa0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
26fb0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
26fc0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
26fd0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
26fe0 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
26ff0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
27000 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
27010 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
27020 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
27030 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
27040 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
27050 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
27060 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
27070 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
27080 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
27090 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
270a0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
270b0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
270c0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
270d0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
270e0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 set..*/.SQLITE_A
270f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
27100 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
27110 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
27120 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
27130 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
27140 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
27150 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
27160 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
27170 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
27180 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
27190 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
271a0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 g16(sqlite3*);.S
271b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
271c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
271d0 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a rstr(int);../*.*
271e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
271f0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
27200 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
27210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27220 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 t} {prepared sta
27230 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 tements}.**.** A
27240 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
27250 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 is object repres
27260 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 ents a single SQ
27270 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 L statement..**
27280 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 This object is v
27290 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 ariously known a
272a0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 s a "prepared st
272b0 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a atement" or a.**
272c0 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 "compiled SQL s
272d0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d tatement" or sim
272e0 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d ply as a "statem
272f0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent"..**.** The
27300 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d life of a statem
27310 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 ent object goes
27320 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 something like t
27330 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
27340 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
27350 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
27360 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
27370 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 _v2()] or a rela
27380 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 ted.** func
27390 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 tion..** <li> Bi
273a0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f nd values to [ho
273b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 st parameters] u
273c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
273d0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
273e0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
273f0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
27400 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
27410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
27420 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
27430 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
27440 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 he statement usi
27450 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
27460 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
27470 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
27480 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
27490 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
274a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
274b0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
274c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
274d0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
274e0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f >.**.** Refer to
274f0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f documentation o
27500 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 n individual met
27510 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 hods above for a
27520 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
27530 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 ormation..*/.typ
27540 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
27550 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
27560 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
27570 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
27580 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 Limits.**.** ^(
27590 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
275a0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
275b0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
275c0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
275d0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
275e0 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
275f0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
27600 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
27610 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
27620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
27630 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
27640 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
27650 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
27660 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
27670 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
27680 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
27690 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
276a0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
276b0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
276c0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
276d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
276e0 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
276f0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
27700 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uct.)^.**.** ^If
27710 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
27720 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
27730 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
27740 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
27750 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 ^(For each limit
27760 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 category SQLITE
27770 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f _LIMIT_<i>NAME</
27780 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a i> there is a .*
27790 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
277a0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
277b0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
277c0 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 time by a C prep
277d0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 rocessor macro c
277e0 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 alled.** [limits
277f0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 | SQLITE_MAX_<i
27800 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 >NAME</i>]..** (
27810 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
27820 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
27830 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
27840 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 ))^.** ^Attempts
27850 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
27860 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
27870 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
27880 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
27890 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
278a0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
278b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 d..**.** ^Regard
278c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
278d0 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 or not the limit
278e0 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 was changed, th
278f0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c e .** [sqlite3_l
27900 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 imit()] interfac
27910 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 e returns the pr
27920 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ior value of the
27930 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 limit..** ^Henc
27940 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 e, to find the c
27950 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
27960 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 a limit without
27970 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 changing it,.**
27980 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 simply invoke th
27990 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 is interface wit
279a0 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 h the third para
279b0 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e meter set to -1.
279c0 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 .**.** Run-time
279d0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
279e0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
279f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
27a00 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
27a10 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
27a20 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
27a30 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
27a40 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
27a50 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
27a60 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
27a70 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
27a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
27a90 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
27aa0 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
27ab0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
27ac0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
27ad0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
27ae0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
27af0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
27b00 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
27b10 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
27b20 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
27b30 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
27b40 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
27b50 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
27b60 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
27b70 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
27b80 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
27b90 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
27ba0 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
27bb0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
27bc0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
27bd0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
27be0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
27bf0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
27c00 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
27c10 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
27c20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
27c30 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
27c40 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
27c50 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
27c60 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
27c70 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
27c80 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
27c90 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
27ca0 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
27cb0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
27cc0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
27cd0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
27ce0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
27cf0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
27d00 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
27d10 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
27d20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
27d30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
27d40 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
27d50 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
27d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
27d70 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
27d80 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
27d90 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
27da0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
27db0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
27dc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
27dd0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
27de0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
27df0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
27e00 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
27e10 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
27e20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
27e30 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
27e40 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
27e50 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
27e60 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
27e70 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
27e80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
27e90 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
27ea0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
27eb0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
27ec0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
27ed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
27ee0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
27ef0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
27f00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
27f10 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
27f20 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
27f30 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 B or table row,
27f40 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a in bytes.<dd>)^.
27f50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
27f60 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d IMIT_SQL_LENGTH]
27f70 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
27f80 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
27f90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
27fa0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
27fb0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
27fc0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 nt, in bytes.</d
27fd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
27fe0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
27ff0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
28000 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 LIMIT_COLUMN</dt
28010 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28020 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
28030 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c olumns in a tabl
28040 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 e definition or
28050 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 in the.** result
28060 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
28070 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 T] or the maximu
28080 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
28090 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
280a0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
280b0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
280c0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a clause.</dd>)^.
280d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
280e0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d IMIT_EXPR_DEPTH]
280f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
28100 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
28110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
28120 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
28130 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
28140 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
28150 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
28160 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
28170 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d OMPOUND_SELECT]]
28180 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
28190 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
281a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
281b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
281c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
281d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
281e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
281f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
28200 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d E_LIMIT_VDBE_OP]
28210 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
28220 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 IMIT_VDBE_OP</dt
28230 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28240 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 imum number of i
28250 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 nstructions in a
28260 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
28270 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 program.** used
28280 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e to implement an
28290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
282a0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e This limit is n
282b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 ot currently.**
282c0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 enforced, though
282d0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 that might be a
282e0 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 dded in some fut
282f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
28300 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e * SQLite.</dd>)^
28310 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
28320 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
28330 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 RG]] ^(<dt>SQLIT
28340 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
28350 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _ARG</dt>.** <dd
28360 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
28370 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
28380 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c on a function.<
28390 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
283a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
283b0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c CHED]] ^(<dt>SQL
283c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
283d0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ED</dt>.** <dd>T
283e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
283f0 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 r of [ATTACH | a
28400 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
28410 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a s].)^</dd>.**.**
28420 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
28430 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
28440 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 GTH]].** ^(<dt>S
28450 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
28460 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c _PATTERN_LENGTH<
28470 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
28480 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
28490 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 f the pattern ar
284a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c gument to the [L
284b0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 IKE] or.** [GLOB
284c0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 ] operators.</dd
284d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
284e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
284f0 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 E_NUMBER]].** ^(
28500 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28510 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
28520 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
28530 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e maximum index n
28540 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 umber of any [pa
28550 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 rameter] in an S
28560 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a QL statement.)^.
28570 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
28580 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
28590 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
285a0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
285b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
285c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
285d0 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e pth of recursion
285e0 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f for triggers.</
285f0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
28600 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
28610 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 _LIMIT_LENGTH
28620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
28630 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
28640 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
28650 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
28660 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
28670 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 TE_LIMIT_COLUMN
28680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
28690 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
286a0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 ITE_LIMIT_EXPR_D
286b0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
286c0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
286d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
286e0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 UND_SELECT
286f0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
28700 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
28710 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 _OP
28720 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
28730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
28740 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 CTION_ARG
28750 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 6.#define
28760 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 SQLITE_LIMIT_AT
28770 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 TACHED
28780 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
28790 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
287a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
287b0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 TH 8.#defi
287c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
287d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 VARIABLE_NUMBER
287e0 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 9.#def
287f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
28800 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 _TRIGGER_DEPTH
28810 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 10../*
28820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
28830 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 mpiling An SQL S
28840 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 tatement.** KEYW
28850 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 ORDS: {SQL state
28860 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a ment compiler}.*
28870 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 *.** To execute
28880 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 an SQL query, it
28890 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 must first be c
288a0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 ompiled into a b
288b0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 yte-code.** prog
288c0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 ram using one of
288d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
288e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
288f0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c argument, "db",
28900 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 is a [database
28910 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 connection] obta
28920 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 ined from a.** p
28930 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
28940 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
28950 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
28960 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 e3_open_v2()] or
28970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
28980 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 n16()]. The dat
28990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
289a0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
289b0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a een closed..**.*
289c0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
289d0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 ument, "zSql", i
289e0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
289f0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 to be compiled,
28a00 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 encoded.** as ei
28a10 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
28a20 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 F-16. The sqlit
28a30 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 e3_prepare() and
28a40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
28a50 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 _v2().** interfa
28a60 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 ces use UTF-8, a
28a70 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
28a80 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 re16() and sqlit
28a90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
28aa0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e ).** use UTF-16.
28ab0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e .**.** ^If the n
28ac0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
28ad0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c less than zero,
28ae0 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
28af0 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 ad up to the.**
28b00 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
28b10 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 nator. ^If nByte
28b20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
28b30 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
28b40 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 maximum.** numb
28b50 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 er of bytes rea
28b60 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 d from zSql. ^W
28b70 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e hen nByte is non
28b80 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a -negative, the.*
28b90 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e * zSql string en
28ba0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 ds at either the
28bb0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 first '\000' or
28bc0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 '\u0000' charac
28bd0 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 ter or.** the nB
28be0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 yte-th byte, whi
28bf0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
28c00 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 st. If the calle
28c10 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 r knows.** that
28c20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
28c30 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
28c40 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 nated, then ther
28c50 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 e is a small.**
28c60 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
28c70 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e ntage to be gain
28c80 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e ed by passing an
28c90 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
28ca0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 that.** is equa
28cb0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 l to the number
28cc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
28cd0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e input string <i>
28ce0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a including</i>.**
28cf0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 the nul-termina
28d00 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 tor bytes as thi
28d10 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 s saves SQLite f
28d20 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a rom having to.**
28d30 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 make a copy of
28d40 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
28d50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 ..**.** ^If pzTa
28d60 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 il is not NULL t
28d70 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d hen *pzTail is m
28d80 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
28d90 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a the first byte.*
28da0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f * past the end o
28db0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 f the first SQL
28dc0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
28dd0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
28de0 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 es only.** compi
28df0 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 le the first sta
28e00 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 tement in zSql,
28e10 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
28e20 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a ft pointing to.*
28e30 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 * what remains u
28e40 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a ncompiled..**.**
28e50 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 ^*ppStmt is lef
28e60 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
28e70 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
28e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
28e90 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
28ea0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
28eb0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e ite3_step()]. ^
28ec0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 If there is an e
28ed0 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 rror, *ppStmt is
28ee0 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e set.** to NULL.
28ef0 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 ^If the input
28f00 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f text contains no
28f10 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
28f20 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a ut is an empty.*
28f30 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f * string or a co
28f40 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 mment) then *ppS
28f50 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 tmt is set to NU
28f60 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 LL..** The calli
28f70 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 ng procedure is
28f80 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
28f90 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d deleting the com
28fa0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 piled.** SQL sta
28fb0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 tement using [sq
28fc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
28fd0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 ] after it has f
28fe0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e inished with it.
28ff0 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e .** ppStmt may n
29000 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ot be NULL..**.*
29010 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 * ^On success, t
29020 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
29030 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 re() family of r
29040 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b outines return [
29050 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f SQLITE_OK];.** o
29060 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
29070 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
29080 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
29090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
290a0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
290b0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
290c0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
290d0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
290e0 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
290f0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
29100 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
29110 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
29120 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
29130 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
29140 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
29150 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 uraged..** ^In t
29160 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
29170 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 es, the prepared
29180 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 statement.** th
29190 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 at is returned (
291a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
291b0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 t] object) conta
291c0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ins a copy of th
291d0 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
291e0 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 L text. This cau
291f0 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ses the [sqlite3
29200 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 _step()] interfa
29210 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 ce to.** behave
29220 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
29230 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a hree ways:.**.**
29240 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a <ol>.** <li>.**
29250 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^If the databas
29260 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 e schema changes
29270 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 , instead of ret
29280 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 urning [SQLITE_S
29290 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 CHEMA] as it.**
292a0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 always used to d
292b0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 o, [sqlite3_step
292c0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ()] will automat
292d0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 ically recompile
292e0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 the SQL.** stat
292f0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f ement and try to
29300 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a run it again..*
29310 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
29320 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 i>.** ^When an e
29330 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 rror occurs, [sq
29340 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
29350 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 ll return one of
29360 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a the detailed.**
29370 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f [error codes] o
29380 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f r [extended erro
29390 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 r codes]. ^The
293a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 legacy behavior
293b0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c was that.** [sql
293c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
293d0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
293e0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 generic [SQLITE
293f0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 _ERROR] result c
29400 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 ode.** and the a
29410 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 pplication would
29420 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 have to make a
29430 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b second call to [
29440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
29450 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 .** in order to
29460 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 find the underly
29470 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 ing cause of the
29480 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 problem. With t
29490 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a he "v2" prepare.
294a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 ** interfaces, t
294b0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 he underlying re
294c0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 ason for the err
294d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 or is returned i
294e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c mmediately..** <
294f0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
29500 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 ** ^If the speci
29510 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 fic value bound
29520 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 to [parameter |
29530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 host parameter]
29540 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 in the .** WHERE
29550 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e clause might in
29560 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 fluence the choi
29570 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e ce of query plan
29580 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 for a statement
29590 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 ,.** then the st
295a0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 atement will be
295b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
295c0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 compiled, as if
295d0 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a there had been .
295e0 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e ** a schema chan
295f0 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 ge, on the first
29600 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 [sqlite3_step(
29610 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e )] call followin
29620 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 g any change.**
29630 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
29640 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 bind_text | bind
29650 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 ings] of that [p
29660 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e arameter]. .** ^
29670 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c The specific val
29680 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 ue of WHERE-clau
29690 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d se [parameter] m
296a0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
296b0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 he .** choice of
296c0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 query plan if t
296d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
296e0 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 the left-hand si
296f0 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a de of a [LIKE].*
29700 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 * or [GLOB] oper
29710 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 ator or if the p
29720 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 arameter is comp
29730 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 ared to an index
29740 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 ed column.** and
29750 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 the [SQLITE_ENA
29760 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 BLE_STAT3] compi
29770 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
29780 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 s enabled..** th
29790 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c e .** </li>.** <
297a0 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 /ol>.*/.SQLITE_A
297b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
297c0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
297d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
297e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
297f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
29800 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
29810 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
29820 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
29830 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
29840 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
29850 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
29860 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
29870 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
29880 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
29890 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
298a0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
298b0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
298c0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
298d0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
298e0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
298f0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
29900 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 int sqlite3_pre
29910 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 pare_v2(. sqlit
29920 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
29930 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
29940 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
29950 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
29960 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
29970 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
29980 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
29990 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
299a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
299b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
299c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
299d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
299e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
299f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
29a00 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
29a10 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
29a20 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
29a30 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
29a40 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
29a50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
29a60 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 epare16(. sqlit
29a70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
29a80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
29a90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
29aa0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
29ab0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
29ac0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
29ad0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
29ae0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
29af0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
29b00 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
29b10 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
29b20 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
29b30 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
29b40 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
29b50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
29b60 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
29b70 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
29b80 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
29b90 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 l */.);.SQLITE_A
29ba0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
29bb0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 repare16_v2(. s
29bc0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
29bd0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
29be0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
29bf0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
29c00 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
29c10 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
29c20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
29c30 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
29c40 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
29c50 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
29c60 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
29c70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
29c80 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
29c90 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
29ca0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
29cb0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
29cc0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
29cd0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
29ce0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a zSql */.);../*.
29cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 ** CAPI3REF: Ret
29d00 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e rieving Statemen
29d10 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 t SQL.**.** ^Thi
29d20 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
29d30 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 be used to retri
29d40 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 eve a saved copy
29d50 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c of the original
29d60 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
29d70 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 d to create a [p
29d80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29d90 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 t] if that state
29da0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 ment was.** comp
29db0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
29dc0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
29dd0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
29de0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
29df0 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 2()]..*/.SQLITE_
29e00 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
29e10 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
29e20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
29e30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29e40 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
29e50 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
29e60 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
29e70 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 base.**.** ^The
29e80 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
29e90 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 donly(X) interfa
29ea0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
29eb0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a (non-zero) if.**
29ec0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
29ed0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29ee0 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f ment] X makes no
29ef0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 direct changes
29f00 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e to.** the conten
29f10 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
29f20 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f e file..**.** No
29f30 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 te that [applica
29f40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
29f50 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a functions] or.*
29f60 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 * [virtual table
29f70 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 s] might change
29f80 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 the database ind
29f90 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 irectly as a sid
29fa0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e e effect. .** ^
29fb0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 (For example, if
29fc0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
29fd0 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 defines a functi
29fe0 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 on "eval()" that
29ff0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 .** calls [sqli
2a000 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 te3_exec()], the
2a010 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
2a020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f SQL statement wo
2a030 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 uld.** change th
2a040 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
2a050 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 through side-eff
2a060 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f ects:.**.** <blo
2a070 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
2a080 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 SELECT eval(
2a090 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 'DELETE FROM t1'
2a0a0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f ) FROM t2;.** </
2a0b0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
2a0c0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 >.**.** But beca
2a0d0 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d use the [SELECT]
2a0e0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
2a0f0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 not change the d
2a100 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 atabase file.**
2a110 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 directly, sqlite
2a120 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2a130 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 ) would still re
2a140 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a turn true.)^.**.
2a150 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 ** ^Transaction
2a160 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e control statemen
2a170 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 ts such as [BEGI
2a180 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 N], [COMMIT], [R
2a190 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 OLLBACK],.** [SA
2a1a0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 VEPOINT], and [R
2a1b0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 ELEASE] cause sq
2a1c0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
2a1d0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 nly() to return
2a1e0 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 true,.** since t
2a1f0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 he statements th
2a200 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 emselves do not
2a210 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 actually modify
2a220 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 the database but
2a230 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 .** rather they
2a240 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 control the timi
2a250 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 ng of when other
2a260 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 statements modi
2a270 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 fy the .** datab
2a280 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 ase. ^The [ATTA
2a290 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d CH] and [DETACH]
2a2a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f statements also
2a2b0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 cause.** sqlite
2a2c0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2a2d0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
2a2e0 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 since, while th
2a2f0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a ose statements.*
2a300 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e * change the con
2a310 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 figuration of a
2a320 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2a330 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 ion, they do not
2a340 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 make .** change
2a350 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 s to the content
2a360 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2a370 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a files on disk..
2a380 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2a390 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
2a3a0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
2a3b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2a3c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2a3d0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
2a3e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2a3f0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
2a400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2a410 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
2a420 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2a430 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
2a440 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
2a450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2a460 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
2a470 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
2a480 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
2a490 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
2a4a0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f t has not run to
2a4b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f completion and/
2a4c0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 or has not .** b
2a4d0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 een reset using
2a4e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2a4f0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 )]. ^The sqlite
2a500 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 3_stmt_busy(S).*
2a510 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
2a520 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 rns false if S i
2a530 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2a540 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 . If S is not a
2a550 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 .** NULL pointe
2a560 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 r and is not a p
2a570 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 ointer to a vali
2a580 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
2a590 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
2a5a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2a5b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
2a5c0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
2a5d0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a desirable..**.**
2a5e0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
2a5f0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 can be used in c
2a600 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 ombination [sqli
2a610 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
2a620 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c .** to locate al
2a630 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 l prepared state
2a640 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 ments associated
2a650 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 with a database
2a660 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 .** connection
2a670 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 that are in need
2a680 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e of being reset.
2a690 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 This can be us
2a6a0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 ed,.** for examp
2a6b0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 le, in diagnosti
2a6c0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 c routines to se
2a6d0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 arch for prepare
2a6e0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 d .** statements
2a6f0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e that are holdin
2a700 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 g a transaction
2a710 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f open..*/.SQLITE_
2a720 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a730 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 stmt_busy(sqlite
2a740 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2a750 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d CAPI3REF: Dynam
2a760 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c ically Typed Val
2a770 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 ue Object.** KEY
2a780 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 WORDS: {protecte
2a790 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d d sqlite3_value}
2a7a0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 {unprotected sq
2a7b0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a lite3_value}.**.
2a7c0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 ** SQLite uses t
2a7d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
2a7e0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 object to repre
2a7f0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a sent all values.
2a800 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 ** that can be s
2a810 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 tored in a datab
2a820 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 ase table. SQLit
2a830 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 e uses dynamic t
2a840 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 yping.** for the
2a850 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 values it store
2a860 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 s. ^Values stor
2a870 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 ed in sqlite3_va
2a880 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 lue objects.** c
2a890 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 an be integers,
2a8a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
2a8b0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 alues, strings,
2a8c0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a BLOBs, or NULL..
2a8d0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 **.** An sqlite3
2a8e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 _value object ma
2a8f0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f y be either "pro
2a900 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 tected" or "unpr
2a910 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d otected"..** Som
2a920 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 e interfaces req
2a930 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 uire a protected
2a940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 sqlite3_value.
2a950 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 Other interface
2a960 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 s.** will accept
2a970 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 either a protec
2a980 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ted or an unprot
2a990 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2a9a0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e lue..** Every in
2a9b0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 terface that acc
2a9c0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c epts sqlite3_val
2a9d0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 ue arguments spe
2a9e0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 cifies.** whethe
2a9f0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 r or not it requ
2aa00 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 ires a protected
2aa10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2aa20 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
2aa30 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
2aa40 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
2aa50 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
2aa60 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
2aa70 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e is held. An in
2aa80 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
2aa90 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
2aaa0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2aab0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
2aac0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
2aad0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
2aae0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2aaf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
2ab00 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2ab10 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
2ab20 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
2ab30 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
2ab40 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
2ab50 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
2ab60 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
2ab70 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
2ab80 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
2ab90 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
2aba0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
2abb0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
2abc0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
2abd0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2abe0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
2abf0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
2ac00 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
2ac10 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
2ac20 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
2ac30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2ac40 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
2ac50 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
2ac60 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
2ac70 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
2ac80 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
2ac90 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
2aca0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
2acb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
2acc0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
2acd0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2ace0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2acf0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2ad00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2ad10 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
2ad20 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
2ad30 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
2ad40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2ad50 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
2ad60 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
2ad70 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
2ad80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2ad90 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
2ada0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2adb0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
2adc0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
2add0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2ade0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
2adf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ae00 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
2ae10 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
2ae20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2ae30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
2ae40 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
2ae50 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
2ae60 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
2ae70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
2ae80 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
2ae90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
2aea0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
2aeb0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
2aec0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
2aed0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2aee0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2aef0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
2af00 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
2af10 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
2af20 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
2af30 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
2af40 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
2af50 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e ct.**.** The con
2af60 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
2af70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
2af80 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
2af90 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
2afa0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
2afb0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f . ^A pointer to
2afc0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 an sqlite3_cont
2afd0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 ext object.** is
2afe0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 always first pa
2aff0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c rameter to [appl
2b000 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2b010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a SQL functions]..
2b020 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
2b030 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2b040 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2b050 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 tation will pass
2b060 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 this.** pointer
2b070 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 through into ca
2b080 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2b090 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c result_int | sql
2b0a0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a ite3_result()],.
2b0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 ** [sqlite3_aggr
2b0c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d egate_context()]
2b0d0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f , [sqlite3_user_
2b0e0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c data()],.** [sql
2b0f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2b100 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 handle()], [sqli
2b110 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
2b120 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 )],.** and/or [s
2b130 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2b140 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 ta()]..*/.typede
2b150 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2b160 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
2b170 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
2b180 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 CAPI3REF: Bindi
2b190 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 ng Values To Pre
2b1a0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 pared Statements
2b1b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
2b1c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
2b1d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
2b1e0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2b1f0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
2b200 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
2b210 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
2b220 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
2b230 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e binding}.**.** ^
2b240 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 (In the SQL stat
2b250 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 ement text input
2b260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
2b270 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 pare_v2()] and i
2b280 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 ts variants,.**
2b290 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 literals may be
2b2a0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 replaced by a [p
2b2b0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d arameter] that m
2b2c0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f atches one of fo
2b2d0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c llowing.** templ
2b2e0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ates:.**.** <ul>
2b2f0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
2b300 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
2b310 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
2b320 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
2b330 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
2b340 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 ** In the templa
2b350 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 tes above, NNN r
2b360 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 epresents an int
2b370 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a eger literal,.**
2b380 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 and VVV represe
2b390 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 nts an alphanume
2b3a0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 ric identifier.)
2b3b0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f ^ ^The values o
2b3c0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d f these.** param
2b3d0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c eters (also call
2b3e0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 ed "host paramet
2b3f0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 er names" or "SQ
2b400 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a L parameters").*
2b410 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 * can be set usi
2b420 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ng the sqlite3_b
2b430 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 ind_*() routines
2b440 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a defined here..*
2b450 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2b460 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
2b470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2b480 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 routines is alw
2b490 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 ays.** a pointer
2b4a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
2b4b0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 _stmt] object re
2b4c0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b turned from.** [
2b4d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2b4e0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 v2()] or its var
2b4f0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 iants..**.** ^Th
2b500 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
2b510 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
2b520 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
2b530 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a ter to be set..*
2b540 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 * ^The leftmost
2b550 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 SQL parameter ha
2b560 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e s an index of 1.
2b570 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 ^When the same
2b580 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 named.** SQL pa
2b590 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 rameter is used
2b5a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
2b5b0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
2b5c0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 quent.** occurre
2b5d0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 nces have the sa
2b5e0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 me index as the
2b5f0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 first occurrence
2b600 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 ..** ^The index
2b610 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 for named parame
2b620 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b ters can be look
2b630 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a ed up using the.
2b640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2b650 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2b660 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 ()] API if desir
2b670 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a ed. ^The index.
2b680 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 ** for "?NNN" pa
2b690 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 rameters is the
2b6a0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a value of NNN..**
2b6b0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 ^The NNN value
2b6c0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 must be between
2b6d0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 1 and the [sqlit
2b6e0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 e3_limit()].** p
2b6f0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 arameter [SQLITE
2b700 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
2b710 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 NUMBER] (default
2b720 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a value: 999)..**
2b730 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 .** ^The third a
2b740 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 rgument is the v
2b750 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 alue to bind to
2b760 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
2b770 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 *.** ^(In those
2b780 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 routines that ha
2b790 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 ve a fourth argu
2b7a0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 ment, its value
2b7b0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
2b7c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2b7d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 parameter. To
2b7e0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 be clear: the va
2b7f0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 lue is the.** nu
2b800 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 mber of <u>bytes
2b810 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 </u> in the valu
2b820 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 e, not the numbe
2b830 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
2b840 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f )^.** ^If the fo
2b850 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
2b860 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2b870 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
2b880 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
2b890 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
2b8a0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f hen the length o
2b8b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a f the string is.
2b8c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2b8d0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 bytes up to the
2b8e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
2b8f0 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 inator..** If th
2b900 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2b910 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2b920 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 nd_blob() is neg
2b930 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 ative, then.** t
2b940 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
2b950 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
2b960 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 a non-negative f
2b970 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
2b980 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 is provided to s
2b990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2b9a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2b9b0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 _bind_text16() t
2b9c0 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 hen that paramet
2b9d0 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 er must be the b
2b9e0 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 yte offset.** wh
2b9f0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d ere the NUL term
2ba00 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 inator would occ
2ba10 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 ur assuming the
2ba20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a string were NUL.
2ba30 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ** terminated.
2ba40 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 If any NUL chara
2ba50 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 cters occur at b
2ba60 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 yte offsets less
2ba70 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 than .** the va
2ba80 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 lue of the fourt
2ba90 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e h parameter then
2baa0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 the resulting s
2bab0 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c tring value will
2bac0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 .** contain embe
2bad0 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 dded NULs. The
2bae0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 result of expres
2baf0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 sions involving
2bb00 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 strings.** with
2bb10 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 embedded NULs is
2bb20 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2bb30 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 * ^The fifth arg
2bb40 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
2bb50 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 _bind_blob(), sq
2bb60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2bb70 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 ), and.** sqlite
2bb80 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
2bb90 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 is a destructor
2bba0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 used to dispose
2bbb0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a of the BLOB or.*
2bbc0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 * string after S
2bbd0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 QLite has finish
2bbe0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 ed with it. ^Th
2bbf0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
2bc00 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 called.** to dis
2bc10 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 pose of the BLOB
2bc20 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 or string even
2bc30 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 if the call to s
2bc40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2bc50 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 (),.** sqlite3_b
2bc60 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 ind_text(), or s
2bc70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2bc80 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 16() fails. .**
2bc90 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 ^If the fifth a
2bca0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 rgument is.** th
2bcb0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 e special value
2bcc0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c [SQLITE_STATIC],
2bcd0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
2bce0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
2bcf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2bd00 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e in static, unman
2bd10 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 aged space and d
2bd20 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 oes not need to
2bd30 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 be freed..** ^If
2bd40 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2bd50 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 ent has the valu
2bd60 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 e [SQLITE_TRANSI
2bd70 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 ENT], then.** SQ
2bd80 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f Lite makes its o
2bd90 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
2bda0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 of the data imme
2bdb0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a diately, before.
2bdc0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 ** the sqlite3_b
2bdd0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 ind_*() routine
2bde0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
2bdf0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
2be00 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 _zeroblob() rout
2be10 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 ine binds a BLOB
2be20 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 of length N tha
2be30 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 t.** is filled w
2be40 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 ith zeroes. ^A
2be50 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 zeroblob uses a
2be60 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 fixed amount of
2be70 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 memory.** (just
2be80 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f an integer to ho
2be90 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 ld its size) whi
2bea0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
2beb0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
2bec0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
2bed0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
2bee0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
2bef0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 BLOBs whose.**
2bf00 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 content is later
2bf10 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a written using.*
2bf20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
2bf30 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 open | increment
2bf40 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 al BLOB I/O] rou
2bf50 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 tines..** ^A neg
2bf60 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 ative value for
2bf70 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 the zeroblob res
2bf80 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c ults in a zero-l
2bf90 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a ength BLOB..**.*
2bfa0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 * ^If any of the
2bfb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
2bfc0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 ) routines are c
2bfd0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
2bfe0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 L pointer.** for
2bff0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2c000 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 tatement] or wit
2c010 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 h a prepared sta
2c020 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 tement for which
2c030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
2c040 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 p()] has been ca
2c050 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 lled more recent
2c060 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 ly than [sqlite3
2c070 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 _reset()],.** th
2c080 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c en the call will
2c090 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2c0a0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 MISUSE]. If any
2c0b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 sqlite3_bind_()
2c0c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 .** routine is p
2c0d0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 assed a [prepare
2c0e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2c0f0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
2c100 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 ized, the.** res
2c110 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
2c120 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 and probably ha
2c130 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 rmful..**.** ^Bi
2c140 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 ndings are not c
2c150 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 leared by the [s
2c160 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c170 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 routine..** ^Unb
2c180 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 ound parameters
2c190 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
2c1a0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e as NULL..**.** ^
2c1b0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 The sqlite3_bind
2c1c0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 _* routines retu
2c1d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
2c1e0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a n success or an.
2c1f0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ** [error code]
2c200 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 if anything goes
2c210 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c wrong..** ^[SQL
2c220 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
2c230 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
2c240 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
2c250 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2c260 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 . ^[SQLITE_NOME
2c270 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
2c280 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
2c290 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2c2a0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2c2b0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2c2c0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2c2d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2c2e0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
2c2f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c300 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2c310 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2c320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2c330 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2c340 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2c350 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
2c360 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2c370 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2c380 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
2c390 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2c3a0 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 , double);.SQLIT
2c3b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2c3c0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
2c3d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
2c3e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2c3f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2c400 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2c410 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
2c420 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 e3_int64);.SQLIT
2c430 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2c440 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 3_bind_null(sqli
2c450 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b te3_stmt*, int);
2c460 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2c470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2c480 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2c490 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
2c4a0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
2c4b0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2c4c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2c4d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 3_bind_text16(sq
2c4e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2c4f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
2c500 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 nt, void(*)(void
2c510 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2c520 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2c530 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2c540 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2c550 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
2c560 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2c570 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2c580 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 roblob(sqlite3_s
2c590 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e tmt*, int, int n
2c5a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2c5b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 EF: Number Of SQ
2c5c0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a L Parameters.**.
2c5d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
2c5e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2c5f0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
2c600 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 of [SQL paramete
2c610 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 rs].** in a [pre
2c620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c630 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 . SQL parameter
2c640 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 s are tokens of
2c650 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c the.** form "?",
2c660 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c "?NNN", ":AAA",
2c670 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 "$AAA", or "@AA
2c680 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 A" that serve as
2c690 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
2c6a0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 for values that
2c6b0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 are [sqlite3_bi
2c6c0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d nd_blob | bound]
2c6d0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d .** to the param
2c6e0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 eters at a later
2c6f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 time..**.** ^(T
2c700 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 his routine actu
2c710 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
2c720 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 index of the la
2c730 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 rgest (rightmost
2c740 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 ).** parameter.
2c750 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 For all forms ex
2c760 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 cept ?NNN, this
2c770 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 will correspond
2c780 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 to the.** number
2c790 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d of unique param
2c7a0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d eters. If param
2c7b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e eters of the ?NN
2c7c0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c N form are used,
2c7d0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 .** there may be
2c7e0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 gaps in the lis
2c7f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 t.)^.**.** See a
2c800 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2c810 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2c820 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2c830 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c840 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
2c850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2c860 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2c870 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2c880 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2c890 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
2c8a0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2c8b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2c8c0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 3REF: Name Of A
2c8d0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a Host Parameter.*
2c8e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2c8f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2c900 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 _name(P,N) inter
2c910 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
2c920 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2c930 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 N-th [SQL parame
2c940 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 ter] in the [pre
2c950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c960 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 P..** ^(SQL par
2c970 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
2c980 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
2c990 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
2c9a0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
2c9b0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
2c9c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
2c9d0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
2c9e0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
2c9f0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
2ca00 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
2ca10 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
2ca20 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
2ca30 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
2ca40 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
2ca50 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a of the name.)^.
2ca60 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f ** ^Parameters o
2ca70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
2ca80 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
2ca90 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
2caa0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
2cab0 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 re referred to a
2cac0 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 s "nameless" or
2cad0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d "anonymous param
2cae0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eters"..**.** ^T
2caf0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
2cb00 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
2cb10 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
2cb20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2cb30 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f value N is out o
2cb40 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
2cb50 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e N-th parameter
2cb60 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
2cb70 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
2cb80 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 turned. ^The re
2cb90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
2cba0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
2cbb0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
2cbc0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
2cbd0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
2cbe0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
2cbf0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
2cc00 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
2cc10 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 re16()] or.** [s
2cc20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2cc30 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
2cc40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2cc50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2cc60 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2cc70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2cc80 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2cc90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2cca0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ccb0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c index()]..*/.SQL
2ccc0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2ccd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
2cce0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
2ccf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2cd00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
2cd10 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
2cd20 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
2cd30 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a A Given Name.**.
2cd40 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 ** ^Return the i
2cd50 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 ndex of an SQL p
2cd60 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 arameter given i
2cd70 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a ts name. ^The.*
2cd80 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
2cd90 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
2cda0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
2cdb0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
2cdc0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
2cdd0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2cde0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 te3_bind()]. ^A
2cdf0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 zero.** is retu
2ce00 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 rned if no match
2ce10 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 ing parameter is
2ce20 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 found. ^The pa
2ce30 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 rameter.** name
2ce40 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e must be given in
2ce50 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 UTF-8 even if t
2ce60 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
2ce70 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 ement.** was pre
2ce80 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 pared from UTF-1
2ce90 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6 text using [sq
2cea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2ceb0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
2cec0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
2ced0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2cee0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
2cef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2cf00 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
2cf10 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2cf20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2cf30 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
2cf40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2cf50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2cf60 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
2cf70 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
2cf80 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
2cf90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2cfa0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
2cfb0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
2cfc0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f tement.**.** ^Co
2cfd0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
2cfe0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
2cff0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2d000 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
2d010 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
2d020 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
2d030 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
2d040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d050 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 ]..** ^Use this
2d060 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
2d070 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
2d080 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f ters to NULL..*/
2d090 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2d0a0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
2d0b0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
2d0c0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
2d0d0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
2d0e0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 f Columns In A R
2d0f0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 esult Set.**.**
2d100 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 ^Return the numb
2d110 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2d120 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
2d130 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
2d140 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2d150 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 tement]. ^This r
2d160 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 outine returns 0
2d170 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 if pStmt is an
2d180 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
2d190 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 that does not r
2d1a0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 eturn data (for
2d1b0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 example an [UPDA
2d1c0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 TE])..**.** See
2d1d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 also: [sqlite3_d
2d1e0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a ata_count()].*/.
2d1f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2d200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
2d210 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2d220 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2d230 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d CAPI3REF: Colum
2d240 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 n Names In A Res
2d250 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult Set.**.** ^T
2d260 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
2d270 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 turn the name as
2d280 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 signed to a part
2d290 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a icular column.**
2d2a0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
2d2b0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d et of a [SELECT]
2d2c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 statement. ^Th
2d2d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2d2e0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 _name().** inter
2d2f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2d300 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f ointer to a zero
2d310 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
2d320 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 8 string.** and
2d330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2d340 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 ame16() returns
2d350 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
2d360 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
2d370 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e * UTF-16 string.
2d380 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 ^The first par
2d390 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 ameter is the [p
2d3a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d3b0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 t].** that imple
2d3c0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 ments the [SELEC
2d3d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 T] statement. ^T
2d3e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2d3f0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f ter is the.** co
2d400 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 lumn number. ^T
2d410 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 he leftmost colu
2d420 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a mn is number 0..
2d430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 **.** ^The retur
2d440 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ned string point
2d450 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 er is valid unti
2d460 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 l either the [pr
2d470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d480 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 ].** is destroye
2d490 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 d by [sqlite3_fi
2d4a0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
2d4b0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
2d4c0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
2d4d0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
2d4e0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
2d4f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2d500 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
2d510 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
2d520 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 until the next
2d530 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 call to.** sqlit
2d540 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
2d550 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
2d560 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 mn_name16() on t
2d570 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a he same column..
2d580 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 **.** ^If sqlite
2d590 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 3_malloc() fails
2d5a0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 during the proc
2d5b0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 essing of either
2d5c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 routine.** (for
2d5d0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 example during
2d5e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f a conversion fro
2d5f0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 m UTF-8 to UTF-1
2d600 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 6) then a.** NUL
2d610 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2d620 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
2d630 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 e name of a resu
2d640 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 lt column is the
2d650 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 value of the "A
2d660 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a S" clause for.**
2d670 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 that column, if
2d680 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 there is an AS
2d690 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 clause. If ther
2d6a0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 e is no AS claus
2d6b0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 e.** then the na
2d6c0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e me of the column
2d6d0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 is unspecified
2d6e0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 and may change f
2d6f0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 rom.** one relea
2d700 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 se of SQLite to
2d710 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c the next..*/.SQL
2d720 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2d730 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2d740 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f mn_name(sqlite3_
2d750 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 stmt*, int N);.S
2d760 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2d770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2d780 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
2d790 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
2d7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2d7b0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
2d7c0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
2d7d0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 sult.**.** ^Thes
2d7e0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 e routines provi
2d7f0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 de a means to de
2d800 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 termine the data
2d810 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 base, table, and
2d820 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e .** table column
2d830 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 that is the ori
2d840 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 gin of a particu
2d850 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d lar result colum
2d860 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d n in.** [SELECT]
2d870 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e statement..** ^
2d880 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
2d890 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c database or tabl
2d8a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 e or column can
2d8b0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a be returned as.*
2d8c0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 * either a UTF-8
2d8d0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
2d8e0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 g. ^The _databa
2d8f0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 se_ routines ret
2d900 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 urn.** the datab
2d910 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 ase name, the _t
2d920 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 able_ routines r
2d930 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 eturn the table
2d940 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 name, and.** the
2d950 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 origin_ routine
2d960 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c s return the col
2d970 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 umn name..** ^Th
2d980 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
2d990 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c g is valid until
2d9a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2d9b0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 tatement] is des
2d9c0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 troyed.** using
2d9d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2d9e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
2d9f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2da00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
2da10 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
2da20 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
2da30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2da40 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
2da50 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
2da60 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
2da70 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
2da80 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
2da90 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
2daa0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ding..**.** ^The
2dab0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 names returned
2dac0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c are the original
2dad0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 un-aliased name
2dae0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 s of the.** data
2daf0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 base, table, and
2db00 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e column..**.** ^
2db10 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2db20 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 nt to these inte
2db30 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 rfaces is a [pre
2db40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2db50 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 ..** ^These func
2db60 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
2db70 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
2db80 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
2db90 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 lumn returned by
2dba0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e .** the statemen
2dbb0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 t, where N is th
2dbc0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f e second functio
2dbd0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e n argument..** ^
2dbe0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f The left-most co
2dbf0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 lumn is column 0
2dc00 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 for these routi
2dc10 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 nes..**.** ^If t
2dc20 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
2dc30 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 turned by the st
2dc40 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 atement is an ex
2dc50 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 pression or.** s
2dc60 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e ubquery and is n
2dc70 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 ot a column valu
2dc80 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 e, then all of t
2dc90 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
2dca0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 eturn.** NULL.
2dcb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d ^These routine m
2dcc0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e ight also return
2dcd0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 NULL if a memor
2dce0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2dcf0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e or.** occurs. ^
2dd00 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 Otherwise, they
2dd10 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
2dd20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 of the attached
2dd30 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
2dd40 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 .** or column th
2dd50 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 at query result
2dd60 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 column was extra
2dd70 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a cted from..**.**
2dd80 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 ^As with all ot
2dd90 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
2dda0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d those whose nam
2ddb0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 es end with "16"
2ddc0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 return.** UTF-1
2ddd0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 6 encoded string
2dde0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 s and the other
2ddf0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2de00 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 UTF-8..**.** ^T
2de10 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e hese APIs are on
2de20 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
2de30 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
2de40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
2de50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
2de60 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
2de70 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
2de80 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a sor symbol..**.*
2de90 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
2dea0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
2deb0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
2dec0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 se routines agai
2ded0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 nst the same.**
2dee0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2def0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 nt and column at
2df00 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
2df10 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
2df20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 are.** undefined
2df30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
2df40 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
2df50 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a all one or more.
2df60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2df70 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2df80 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 | column metada
2df90 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a ta interfaces].*
2dfa0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b * for the same [
2dfb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2dfc0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 nt] and result c
2dfd0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 olumn.** at the
2dfe0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2dff0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
2e000 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c ndefined..*/.SQL
2e010 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2e020 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2e030 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2e040 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2e050 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2e060 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2e070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2e080 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ase_name16(sqlit
2e090 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2e0a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2e0b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2e0c0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 lumn_table_name(
2e0d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2e0e0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2e0f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2e100 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2e110 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2e120 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
2e130 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2e140 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2e150 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c _origin_name(sql
2e160 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2e170 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2e180 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2e190 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
2e1a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
2e1b0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
2e1c0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
2e1d0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
2e1e0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
2e1f0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 .** ^(The first
2e200 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b parameter is a [
2e210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e220 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 nt]..** If this
2e230 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
2e240 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2e250 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f t and the Nth co
2e260 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 lumn of the.** r
2e270 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 eturned result s
2e280 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 et of that [SELE
2e290 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 CT] is a table c
2e2a0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a olumn (not an.**
2e2b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 expression or s
2e2c0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 ubquery) then th
2e2d0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 e declared type
2e2e0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 of the table.**
2e2f0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e column is return
2e300 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e ed.)^ ^If the N
2e310 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 th column of the
2e320 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 result set is a
2e330 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
2e340 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 or subquery, the
2e350 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
2e360 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2e370 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2e380 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 tring is always
2e390 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a UTF-8 encoded..*
2e3a0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 *.** ^(For examp
2e3b0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 le, given the da
2e3c0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a tabase schema:.*
2e3d0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c *.** CREATE TABL
2e3e0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 E t1(c1 VARIANT)
2e3f0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ;.**.** and the
2e400 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d following statem
2e410 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
2e420 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
2e430 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
2e440 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 t1;.**.** this
2e450 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 routine would re
2e460 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 turn the string
2e470 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 "VARIANT" for th
2e480 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a e second result.
2e490 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 ** column (i==1)
2e4a0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 , and a NULL poi
2e4b0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 nter for the fir
2e4c0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e st result column
2e4d0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a (i==0).)^.**.**
2e4e0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 ^SQLite uses dy
2e4f0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 namic run-time t
2e500 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 yping. ^So just
2e510 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d because a colum
2e520 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 n.** is declared
2e530 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 to contain a pa
2e540 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f rticular type do
2e550 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 es not mean that
2e560 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f the.** data sto
2e570 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 red in that colu
2e580 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 mn is of the dec
2e590 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c lared type. SQL
2e5a0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 ite is.** strong
2e5b0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 ly typed, but th
2e5c0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 e typing is dyna
2e5d0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 mic not static.
2e5e0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 ^Type.** is ass
2e5f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 ociated with ind
2e600 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 ividual values,
2e610 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e not with the con
2e620 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 tainers.** used
2e630 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 to hold those va
2e640 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f lues..*/.SQLITE_
2e650 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
2e660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2e670 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
2e680 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2e690 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2e6a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2e6b0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c n_decltype16(sql
2e6c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2e6d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e6e0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 : Evaluate An SQ
2e6f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a L Statement.**.*
2e700 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
2e710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
2e720 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
2e730 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
2e740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e750 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
2e760 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2e770 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
2e780 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
2e790 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
2e7a0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
2e7b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2e7c0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
2e7d0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
2e7e0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
2e7f0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
2e800 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
2e810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
2e820 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
2e830 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
2e840 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
2e850 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
2e860 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
2e870 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
2e880 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
2e890 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
2e8a0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
2e8b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2e8c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e8d0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
2e8e0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
2e8f0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
2e900 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
2e910 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2e920 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
2e930 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
2e940 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
2e950 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
2e960 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
2e970 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
2e980 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2e990 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
2e9a0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
2e9b0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
2e9c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
2e9d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
2e9e0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
2e9f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
2ea00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
2ea10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
2ea20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
2ea30 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2ea40 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
2ea50 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
2ea60 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
2ea70 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
2ea80 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
2ea90 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
2eaa0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
2eab0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
2eac0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
2ead0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
2eae0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
2eaf0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
2eb00 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
2eb10 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
2eb20 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
2eb30 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
2eb40 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
2eb50 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
2eb60 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
2eb70 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
2eb80 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
2eb90 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
2eba0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
2ebb0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
2ebc0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
2ebd0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a ccurs within an.
2ebe0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
2ebf0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
2ec00 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
2ec10 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
2ec20 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
2ec30 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
2ec40 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
2ec50 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
2ec60 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
2ec70 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
2ec80 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
2ec90 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
2eca0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
2ecb0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
2ecc0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
2ecd0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
2ece0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2ecf0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
2ed00 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
2ed10 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
2ed20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
2ed30 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
2ed40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
2ed50 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
2ed60 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
2ed70 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
2ed80 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
2ed90 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
2eda0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
2edb0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
2edc0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
2edd0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
2ede0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
2edf0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
2ee00 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
2ee10 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
2ee20 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
2ee30 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
2ee40 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
2ee50 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
2ee60 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
2ee70 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
2ee80 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
2ee90 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
2eea0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
2eeb0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
2eec0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
2eed0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
2eee0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
2eef0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
2ef00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
2ef10 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
2ef20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
2ef30 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
2ef40 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2ef50 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
2ef60 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
2ef70 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
2ef80 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
2ef90 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
2efa0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
2efb0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
2efc0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
2efd0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
2efe0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
2eff0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
2f000 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2f010 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
2f020 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
2f030 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
2f040 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
2f050 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
2f060 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
2f070 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
2f080 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
2f090 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
2f0a0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
2f0b0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
2f0c0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
2f0d0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
2f0e0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
2f0f0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
2f100 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
2f110 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
2f120 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
2f130 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
2f140 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
2f150 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
2f160 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
2f170 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
2f180 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
2f190 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
2f1a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
2f1b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
2f1c0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
2f1d0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
2f1e0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
2f1f0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
2f200 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 *.** For all ver
2f210 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
2f220 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 up to and includ
2f230 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 ing 3.6.23.1, a
2f240 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2f250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 te3_reset()] was
2f260 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 required after
2f270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 sqlite3_step() r
2f280 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 eturned anything
2f290 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b .** other than [
2f2a0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f SQLITE_ROW] befo
2f2b0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e re any subsequen
2f2c0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a t invocation of.
2f2d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
2f2e0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 ). Failure to r
2f2f0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
2f300 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
2f310 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 g .** [sqlite3_r
2f320 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 eset()] would re
2f330 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 sult in an [SQLI
2f340 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 TE_MISUSE] retur
2f350 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 n from.** sqlite
2f360 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 3_step(). But a
2f370 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 fter version 3.6
2f380 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 .23.1, sqlite3_s
2f390 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
2f3a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2f3b0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
2f3c0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
2f3d0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
2f3e0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
2f3f0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
2f400 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
2f410 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
2f420 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
2f430 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
2f440 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
2f450 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
2f460 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
2f470 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
2f480 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
2f490 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
2f4a0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
2f4b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2f4c0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
2f4d0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
2f4e0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
2f4f0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
2f500 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
2f510 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
2f520 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2f530 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
2f540 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
2f550 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
2f560 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
2f570 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2f580 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
2f590 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
2f5a0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
2f5b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
2f5c0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
2f5d0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
2f5e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
2f5f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2f600 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
2f610 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
2f620 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
2f630 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
2f640 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
2f650 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
2f660 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
2f670 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
2f680 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
2f690 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
2f6a0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
2f6b0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
2f6c0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
2f6d0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
2f6e0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 ents.** using ei
2f6f0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
2f700 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
2f710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2f720 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v2()] instead.
2f730 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
2f740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2f750 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2f760 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
2f770 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
2f780 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
2f790 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
2f7a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
2f7b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
2f7c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2f7d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
2f7e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
2f7f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f recommended..*/
2f800 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f810 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
2f820 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2f830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2f840 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2f850 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a in a result set.
2f860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2f870 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2f880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2f890 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2f8a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
2f8b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f ** current row o
2f8c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2f8d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
2f8e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
2f8f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 If prepared stat
2f900 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 ement P does not
2f910 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 have results re
2f920 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ady to return.**
2f930 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 (via calls to t
2f940 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2f950 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 mn_int | sqlite3
2f960 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a _column_*()] of.
2f970 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 ** interfaces) t
2f980 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 hen sqlite3_data
2f990 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e _count(P) return
2f9a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s 0..** ^The sql
2f9b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2f9c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 P) routine also
2f9d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 returns 0 if P i
2f9e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2f9f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2fa00 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2fa10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2fa20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 0 if the previou
2fa30 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 s call to.** [sq
2fa40 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 lite3_step](P) r
2fa50 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2fa60 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c DONE]. ^The sql
2fa70 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2fa80 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 P).** will retur
2fa90 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 n non-zero if pr
2faa0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b evious call to [
2fab0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
2fac0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 returned.** [SQ
2fad0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 LITE_ROW], excep
2fae0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 t in the case of
2faf0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 the [PRAGMA inc
2fb00 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d remental_vacuum]
2fb10 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 .** where it alw
2fb20 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ays returns zero
2fb30 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 since each step
2fb40 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 of that multi-s
2fb50 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 tep.** pragma re
2fb60 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 turns 0 columns
2fb70 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 of data..**.** S
2fb80 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2fb90 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
2fba0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ].*/.SQLITE_API
2fbb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 int sqlite3_data
2fbc0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
2fbd0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2fbe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
2fbf0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 ndamental Dataty
2fc00 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
2fc10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a SQLITE_TEXT.**.
2fc20 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 ** ^(Every value
2fc30 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f in SQLite has o
2fc40 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 ne of five funda
2fc50 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 mental datatypes
2fc60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2fc70 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e <li> 64-bit sign
2fc80 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c ed integer.** <l
2fc90 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 i> 64-bit IEEE f
2fca0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
2fcb0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 mber.** <li> str
2fcc0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 ing.** <li> BLOB
2fcd0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a .** <li> NULL.**
2fce0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
2fcf0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
2fd00 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
2fd10 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
2fd20 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
2fd30 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
2fd40 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
2fd50 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
2fd60 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
2fd70 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
2fd80 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
2fd90 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
2fda0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
2fdb0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
2fdc0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
2fdd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
2fde0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
2fdf0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
2fe00 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
2fe10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2fe20 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
2fe30 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
2fe40 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2fe50 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
2fe60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
2fe70 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
2fe80 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
2fe90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
2fea0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
2feb0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
2fec0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
2fed0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
2fee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fef0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
2ff00 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 From A Query.**
2ff10 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
2ff20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
2ff30 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
2ff40 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 routines form th
2ff50 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 e "result set" i
2ff60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
2ff70 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2ff80 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
2ff90 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c on about a singl
2ffa0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
2ffb0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c current.** resul
2ffc0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 t row of a query
2ffd0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 . ^In every cas
2ffe0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 e the first argu
2fff0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
30000 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 r.** to the [pre
30010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30020 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 that is being e
30030 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 valuated (the [s
30040 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a qlite3_stmt*].**
30050 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e that was return
30060 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
30070 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
30080 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 r one of its var
30090 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 iants).** and th
300a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
300b0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f t is the index o
300c0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 f the column for
300d0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 which informati
300e0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
300f0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c returned. ^The l
30100 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f eftmost column o
30110 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
30120 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 has the index 0
30130 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 ..** ^The number
30140 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
30150 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 he result can be
30160 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e determined usin
30170 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f g.** [sqlite3_co
30180 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a lumn_count()]..*
30190 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
301a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
301b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 ot currently poi
301c0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f nt to a valid ro
301d0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 w, or if the.**
301e0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 column index is
301f0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
30200 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 e result is unde
30210 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 fined..** These
30220 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c routines may onl
30230 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e y be called when
30240 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
30250 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
30260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
30270 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
30280 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 E_ROW] and neith
30290 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 er.** [sqlite3_r
302a0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c eset()] nor [sql
302b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
302c0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 have been calle
302d0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a d subsequently..
302e0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 ** If any of the
302f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
30300 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
30310 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
30320 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 r.** [sqlite3_fi
30330 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 nalize()] or aft
30340 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
30350 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 ()] has returned
30360 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 .** something ot
30370 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
30380 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c _ROW], the resul
30390 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
303a0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 ..** If [sqlite3
303b0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c _step()] or [sql
303c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
303d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
303e0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c ze()].** are cal
303f0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 led from a diffe
30400 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c rent thread whil
30410 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 e any of these r
30420 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 outines.** are p
30430 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 ending, then the
30440 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
30450 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
30460 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
30470 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 n_type() routine
30480 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
30490 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
304a0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d | datatype code]
304b0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c for the initial
304c0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 data type.** of
304d0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 the result colu
304e0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e mn. ^The return
304f0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 ed value is one
30500 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 of [SQLITE_INTEG
30510 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ER],.** [SQLITE_
30520 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f FLOAT], [SQLITE_
30530 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 TEXT], [SQLITE_B
30540 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 LOB], or [SQLITE
30550 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c _NULL]. The val
30560 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
30570 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
30580 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 _type() is only
30590 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f meaningful if no
305a0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 type.** convers
305b0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 ions have occurr
305c0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 ed as described
305d0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 below. After a
305e0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c type conversion,
305f0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 .** the value re
30600 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
30610 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
30620 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 is undefined. F
30630 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
30640 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 s of SQLite may
30650 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 change the behav
30660 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 ior of sqlite3_c
30670 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 olumn_type().**
30680 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 following a type
30690 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a conversion..**.
306a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
306b0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 t is a BLOB or U
306c0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e TF-8 string then
306d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
306e0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 umn_bytes().** r
306f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
30700 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
30710 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
30720 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
30730 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
30740 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c a UTF-16 string,
30750 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
30760 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e lumn_bytes() con
30770 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
30780 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 ing to UTF-8 and
30790 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
307a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
307b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 s..** ^If the re
307c0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 sult is a numeri
307d0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c c value then sql
307e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
307f0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c s() uses.** [sql
30800 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
30810 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 to convert that
30820 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d value to a UTF-
30830 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 8 string and ret
30840 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 urns.** the numb
30850 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
30860 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e hat string..** ^
30870 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
30880 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 NULL, then sqli
30890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
308a0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e () returns zero.
308b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 .**.** ^If the r
308c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
308d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
308e0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
308f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
30900 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 ().** routine re
30910 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
30920 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
30930 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 t BLOB or string
30940 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
30950 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 ult is a UTF-8 s
30960 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 tring, then sqli
30970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30980 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 16() converts.**
30990 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
309a0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 TF-16 and then r
309b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
309c0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
309d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
309e0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
309f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
30a00 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 lumn_bytes16() u
30a10 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
30a20 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
30a30 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
30a40 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 e to a UTF-16 st
30a50 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
30a60 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
30a70 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
30a80 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
30a90 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c he result is NUL
30aa0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f L, then sqlite3_
30ab0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
30ac0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
30ad0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 *.** ^The values
30ae0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
30af0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30b00 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 es()] and .** [s
30b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
30b20 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 tes16()] do not
30b30 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f include the zero
30b40 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 terminators at
30b50 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 the end.** of th
30b60 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 e string. ^For
30b70 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c clarity: the val
30b80 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a ues returned by.
30b90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
30ba0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 mn_bytes()] and
30bb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
30bc0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 bytes16()] are t
30bd0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
30be0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 bytes in the str
30bf0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d ing, not the num
30c00 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
30c10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 s..**.** ^String
30c20 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 s returned by sq
30c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30c40 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
30c50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c column_text16(),
30c60 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 .** even empty s
30c70 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 trings, are alwa
30c80 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 ys zero-terminat
30c90 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e ed. ^The return
30ca0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 .** value from s
30cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
30cc0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d ob() for a zero-
30cd0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 length BLOB is a
30ce0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
30cf0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 *.** ^The object
30d00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
30d10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
30d20 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b ue()] is an.** [
30d30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
30d40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
30d50 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 t. An unprotect
30d60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30d70 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f object.** may o
30d80 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
30d90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
30da0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
30db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
30dc0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 e()]..** If the
30dd0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
30de0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
30df0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
30e00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
30e10 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 n_value()] is us
30e20 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 ed in any other
30e30 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 way, including c
30e40 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 alls.** to routi
30e50 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
30e60 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 3_value_int()],
30e70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
30e80 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
30e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
30ea0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 es()], then the
30eb0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
30ec0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fined..**.** The
30ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 se routines atte
30ee0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 mpt to convert t
30ef0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 he value where a
30f00 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f ppropriate. ^Fo
30f10 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 r.** example, if
30f20 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
30f30 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
30f40 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 FLOAT and a text
30f50 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 result.** is re
30f60 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 quested, [sqlite
30f70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 3_snprintf()] is
30f80 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
30f90 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a to perform the.
30fa0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 ** conversion au
30fb0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 tomatically. ^(
30fc0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 The following ta
30fd0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 ble details the
30fe0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 conversions.** t
30ff0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a hat are applied:
31000 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
31010 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f te>.** <table bo
31020 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 rder="1">.** <tr
31030 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 ><th> Internal<b
31040 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 r>Type <th> Requ
31050 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 ested<br>Type <t
31060 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a h> Conversion.*
31070 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e *.** <tr><td> N
31080 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 ULL <td> INTE
31090 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c GER <td> Resul
310a0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 t is 0.** <tr><t
310b0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
310c0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
310d0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a Result is 0.0.**
310e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
310f0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
31100 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
31110 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
31120 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
31130 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
31140 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
31150 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
31160 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
31170 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
31180 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
31190 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
311a0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
311b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
311c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
311d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
311e0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
311f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
31200 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
31210 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e <td> Same as IN
31220 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c TEGER->TEXT.** <
31230 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
31240 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
31250 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f <td> Convert fro
31260 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 m float to integ
31270 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
31280 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 FLOAT <td> T
31290 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
312a0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
312b0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e he float.** <tr>
312c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
312d0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
312e0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d > Same as FLOAT-
312f0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
31300 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
31310 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 INTEGER <td> U
31320 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
31330 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
31340 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
31350 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a d> Use atof().**
31360 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
31370 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
31380 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
31390 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
313a0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
313b0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 ER <td> Conver
313c0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 t to TEXT then u
313d0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 se atoi().** <tr
313e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
313f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
31400 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
31410 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 XT then use atof
31420 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
31430 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 BLOB <td> T
31440 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 EXT <td> Add
31450 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f a zero terminato
31460 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c r if needed.** <
31470 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f /table>.** </blo
31480 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
31490 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 The table above
314a0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 makes reference
314b0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c to standard C l
314c0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 ibrary functions
314d0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 atoi().** and a
314e0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 tof(). SQLite d
314f0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 oes not really u
31500 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f se these functio
31510 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a ns. It has its.
31520 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e ** own equivalen
31530 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 t internal routi
31540 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 nes. The atoi()
31550 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 and atof() name
31560 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e s are.** used in
31570 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 the table for b
31580 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 revity and becau
31590 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 se they are fami
315a0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 liar to most.**
315b0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a C programmers..*
315c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
315d0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
315e0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
315f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
31600 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
31610 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
31620 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
31630 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
31640 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
31650 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
31660 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
31670 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 dated..** Type c
31680 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 onversions and p
31690 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 ointer invalidat
316a0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 ions might occur
316b0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f .** in the follo
316c0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a wing cases:.**.*
316d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
316e0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
316f0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
31700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31710 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 text() or.**
31720 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
31730 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
31740 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 led. A zero-ter
31750 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a minator might.**
31760 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 need to be
31770 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 added to the st
31780 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c ring.</li>.** <l
31790 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 i> The initial c
317a0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 ontent is UTF-8
317b0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
317c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
317d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
317e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
317f0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
31800 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
31810 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
31820 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 * to UTF-16
31830 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
31840 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
31850 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 nt is UTF-16 tex
31860 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
31870 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
31880 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
31890 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
318a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
318b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
318c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
318d0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a to UTF-8.</li>.*
318e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 * </ul>.**.** ^C
318f0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 onversions betwe
31900 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 en UTF-16be and
31910 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 UTF-16le are alw
31920 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 ays done in plac
31930 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 e and do.** not
31940 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 invalidate a pri
31950 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 or pointer, thou
31960 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 gh of course the
31970 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
31980 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 buffer.** that t
31990 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 he prior pointer
319a0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c references will
319b0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 have been modif
319c0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 ied. Other kind
319d0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 s.** of conversi
319e0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 on are done in p
319f0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 lace when it is
31a00 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f possible, but so
31a10 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 metimes they.**
31a20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 are not possible
31a30 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 and in those ca
31a40 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 ses prior pointe
31a50 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 rs are invalidat
31a60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 ed..**.** The sa
31a70 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 fest and easiest
31a80 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c to remember pol
31a90 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 icy is to invoke
31aa0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
31ab0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 ** in one of the
31ac0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a following ways:
31ad0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
31ae0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
31af0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 mn_text() follow
31b00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
31b10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
31b20 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
31b30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
31b40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
31b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31b60 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
31b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
31b80 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 ext16() followed
31b90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
31ba0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 mn_bytes16()</li
31bb0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
31bc0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
31bd0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c you should call
31be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
31bf0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 text(),.** sqlit
31c00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
31c10 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c , or sqlite3_col
31c20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 umn_text16() fir
31c30 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 st to force the
31c40 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 result.** into t
31c50 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 he desired forma
31c60 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 t, then invoke s
31c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31c80 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 tes() or.** sqli
31c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
31ca0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 16() to find the
31cb0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 size of the res
31cc0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 ult. Do not mix
31cd0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c calls.** to sql
31ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
31cf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
31d00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 lumn_blob() with
31d10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c calls to.** sql
31d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
31d30 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f s16(), and do no
31d40 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 t mix calls to s
31d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
31d60 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 xt16().** with c
31d70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
31d80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a column_bytes()..
31d90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 **.** ^The point
31da0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 ers returned are
31db0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 valid until a t
31dc0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f ype conversion o
31dd0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 ccurs as.** desc
31de0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 ribed above, or
31df0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 until [sqlite3_s
31e00 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
31e10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
31e20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
31e30 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ize()] is called
31e40 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 . ^The memory s
31e50 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c pace used to hol
31e60 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 d strings.** and
31e70 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 BLOBs is freed
31e80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
31e90 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 Do <b>not</b> pa
31ea0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 ss the pointers
31eb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c returned.** [sql
31ec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
31ed0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f ()], [sqlite3_co
31ee0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 lumn_text()], et
31ef0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 c. into.** [sqli
31f00 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a te3_free()]..**.
31f10 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 ** ^(If a memory
31f20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
31f30 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
31f40 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f the evaluation o
31f50 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 f any.** of thes
31f60 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 e routines, a de
31f70 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 fault value is r
31f80 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 eturned. The de
31f90 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 fault value.** i
31fa0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 s either the int
31fb0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 eger 0, the floa
31fc0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
31fd0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c r 0.0, or a NULL
31fe0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 .** pointer. Su
31ff0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
32000 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f o [sqlite3_errco
32010 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 de()] will retur
32020 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d n.** [SQLITE_NOM
32030 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 EM].)^.*/.SQLITE
32040 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
32050 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
32060 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
32070 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
32080 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
32090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
320a0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a es(sqlite3_stmt*
320b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
320c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
320d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
320e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
320f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
32100 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 ITE_API double s
32110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
32120 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
32130 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
32140 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
32150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
32160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
32170 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
32180 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
32190 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t64 sqlite3_colu
321a0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 mn_int64(sqlite3
321b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
321c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
321d0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
321e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
321f0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
32200 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
32210 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
32220 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
32230 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 column_text16(sq
32240 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
32250 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
32260 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
32270 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 olumn_type(sqlit
32280 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
32290 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
322a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 sqlite3_value *s
322b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
322c0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
322d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f *, int iCol);../
322e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
322f0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 estroy A Prepare
32300 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
32310 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ct.**.** ^The sq
32320 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
32330 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
32340 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 led to delete a
32350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
32360 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ent]..** ^If the
32370 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
32380 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 luation of the s
32390 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 tatement encount
323a0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a ered no errors.*
323b0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 * or if the stat
323c0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 ement is never b
323d0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 een evaluated, t
323e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 hen sqlite3_fina
323f0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a lize() returns.*
32400 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 * SQLITE_OK. ^I
32410 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
32420 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
32430 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c statement S fail
32440 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 ed, then.** sqli
32450 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
32460 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 returns the appr
32470 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
32480 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
32490 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
324a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
324b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
324c0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
324d0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f called at any po
324e0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 int during.** th
324f0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 e life cycle of
32500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
32510 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 ent] S:.** befor
32520 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 e statement S is
32530 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c ever evaluated,
32540 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 after.** one or
32550 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b more calls to [
32560 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
32570 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 , or after any c
32580 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 all.** to [sqlit
32590 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 e3_step()] regar
325a0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
325b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 or not the stat
325c0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d ement has.** com
325d0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e pleted execution
325e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e ..**.** ^Invokin
325f0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 g sqlite3_finali
32600 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 ze() on a NULL p
32610 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d ointer is a harm
32620 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a less no-op..**.*
32630 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
32640 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 n must finalize
32650 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 every [prepared
32660 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 statement] in or
32670 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 der to avoid.**
32680 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 resource leaks.
32690 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 It is a grievou
326a0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 s error for the
326b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 application to t
326c0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 ry to use.** a p
326d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
326e0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
326f0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 een finalized.
32700 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 Any use of a pre
32710 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
32720 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
32730 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 been finalized c
32740 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 an result in und
32750 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e efined and.** un
32760 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 desirable behavi
32770 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 or such as segfa
32780 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f ults and heap co
32790 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c rruption..*/.SQL
327a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
327b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
327c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
327d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
327e0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
327f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
32800 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 bject.**.** The
32810 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 sqlite3_reset()
32820 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
32830 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 ed to reset a [p
32840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
32850 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 t].** object bac
32860 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
32870 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f state, ready to
32880 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e be re-executed.
32890 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 .** ^Any SQL sta
328a0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 tement variables
328b0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 that had values
328c0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 bound to them u
328d0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c sing.** the [sql
328e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
328f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
32900 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 ) API] retain th
32910 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 eir values..** U
32920 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 se [sqlite3_clea
32930 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f r_bindings()] to
32940 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 reset the bindi
32950 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ngs..**.** ^The
32960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
32970 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 )] interface res
32980 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 ets the [prepare
32990 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a d statement] S.*
329a0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 * back to the be
329b0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 ginning of its p
329c0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 rogram..**.** ^I
329d0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
329e0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
329f0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
32a00 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
32a10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
32a20 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
32a30 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 OW] or [SQLITE_D
32a40 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b ONE],.** or if [
32a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
32a60 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 has never befor
32a70 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e e been called on
32a80 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c S,.** then [sql
32a90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
32aa0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
32ab0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 K]..**.** ^If th
32ac0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
32ad0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
32ae0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
32af0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
32b00 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 tement] S indica
32b10 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 ted an error, th
32b20 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 en.** [sqlite3_r
32b30 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
32b40 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
32b50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a [error code]..**
32b60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
32b70 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 3_reset(S)] inte
32b80 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 rface does not c
32b90 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 hange the values
32ba0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 .** of any [sqli
32bb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 te3_bind_blob|bi
32bc0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b ndings] on the [
32bd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32be0 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nt] S..*/.SQLITE
32bf0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
32c00 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
32c10 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
32c20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
32c30 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
32c40 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a SQL Functions.*
32c50 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e * KEYWORDS: {fun
32c60 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
32c70 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 outines}.** KEYW
32c80 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
32c90 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
32ca0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 unction}.** KEYW
32cb0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 ORDS: {applicati
32cc0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
32cd0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
32ce0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
32cf0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
32d00 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
32d10 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
32d20 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
32d30 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
32d40 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
32d50 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
32d60 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
32d70 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
32d80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
32d90 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
32da0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
32db0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
32dc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
32dd0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
32de0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
32df0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
32e00 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
32e10 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
32e20 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
32e30 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
32e40 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
32e50 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
32e60 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
32e70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32e80 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
32e90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
32ea0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
32eb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
32ec0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
32ed0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
32ee0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
32ef0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
32f00 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
32f10 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
32f20 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
32f30 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
32f40 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
32f50 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
32f60 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
32f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
32f80 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
32f90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
32fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
32fb0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
32fc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
32fd0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
32fe0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
32ff0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
33000 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
33010 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
33020 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
33030 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
33040 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
33050 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
33060 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
33070 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
33080 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
33090 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
330a0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
330b0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
330c0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
330d0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
330e0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
330f0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
33100 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
33110 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
33120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
33130 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
33140 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
33150 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
33160 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
33170 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
33180 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
33190 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
331a0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
331b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
331c0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
331d0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
331e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
331f0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
33200 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
33210 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
33220 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
33230 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
33240 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
33250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
33260 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
33270 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
33280 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
33290 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
332a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
332b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
332c0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
332d0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
332e0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
332f0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
33300 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
33310 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
33320 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 rameters. Every
33330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d SQL function im
33340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 plementation mus
33350 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 t be able to wor
33360 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c k.** with UTF-8,
33370 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 UTF-16le, or UT
33380 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d F-16be. But som
33390 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
333a0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 s may be.** more
333b0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 efficient with
333c0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 one encoding tha
333d0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 n another. ^An
333e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a application may.
333f0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
33400 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33410 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
33420 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
33430 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 () multiple.** t
33440 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
33450 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 me function but
33460 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 with different v
33470 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 alues of eTextRe
33480 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 p..** ^When mult
33490 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 iple implementat
334a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
334b0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 function are av
334c0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a ailable, SQLite.
334d0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 ** will pick the
334e0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 one that involv
334f0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f es the least amo
33500 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 unt of data conv
33510 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 ersion..** If th
33520 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 ere is only a si
33530 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ngle implementat
33540 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e ion which does n
33550 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 ot care what tex
33560 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 t.** encoding is
33570 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 used, then the
33580 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
33590 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 should be [SQLIT
335a0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 E_ANY]..**.** ^(
335b0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 The fifth parame
335c0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 ter is an arbitr
335d0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 ary pointer. Th
335e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
335f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 of the.** funct
33600 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 ion can gain acc
33610 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e ess to this poin
33620 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ter using [sqlit
33630 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
33640 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 )^.**.** ^The si
33650 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 xth, seventh and
33660 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 eighth paramete
33670 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 rs, xFunc, xStep
33680 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 and xFinal, are
33690 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
336a0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 C-language funct
336b0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d ions that implem
336c0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
336d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
336e0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 gate. ^A scalar
336f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
33700 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
33710 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 ntation of the x
33720 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b Func.** callback
33730 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e only; NULL poin
33740 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 ters must be pas
33750 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
33760 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 and xFinal.** p
33770 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 arameters. ^An a
33780 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
33790 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
337a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
337b0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 of xStep.** and
337c0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c xFinal and NULL
337d0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 pointer must be
337e0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e passed for xFun
337f0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e c. ^To delete an
33800 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c existing.** SQL
33810 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
33820 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c regate, pass NUL
33830 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 L pointers for a
33840 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f ll three functio
33850 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a n.** callbacks..
33860 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e **.** ^(If the n
33870 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 inth parameter t
33880 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
33890 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 _function_v2() i
338a0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 s not NULL,.** t
338b0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 hen it is destru
338c0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 ctor for the app
338d0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
338e0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 inter. .** The d
338f0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 estructor is inv
33900 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 oked when the fu
33910 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 nction is delete
33920 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 d, either by bei
33930 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 ng.** overloaded
33940 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 or when the dat
33950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
33960 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 closes.)^.** ^T
33970 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
33980 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 also invoked if
33990 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
339a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
339b0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 unction_v2() fai
339c0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 ls..** ^When the
339d0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c destructor call
339e0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 back of the tent
339f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 h parameter is i
33a00 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 nvoked, it.** is
33a10 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 passed a single
33a20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
33a30 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
33a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
33a50 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 a .** pointer wh
33a60 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 ich was the fift
33a70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
33a80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
33a90 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a nction_v2()..**.
33aa0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 ** ^It is permit
33ab0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
33ac0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
33ad0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
33ae0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
33af0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
33b00 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
33b10 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
33b20 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
33b30 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
33b40 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 ing preferred te
33b50 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e xt encodings. ^
33b60 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
33b70 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ** the implement
33b80 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 ation that most
33b90 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 closely matches
33ba0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 the way in which
33bb0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 the.** SQL func
33bc0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e tion is used. ^
33bd0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 A function imple
33be0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
33bf0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a non-negative.**
33c00 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 nArg parameter
33c10 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 is a better matc
33c20 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
33c30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
33c40 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 with.** a negat
33c50 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 ive nArg. ^A fu
33c60 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
33c70 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
33c80 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 encoding.** matc
33c90 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 hes the database
33ca0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 encoding is a b
33cb0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 etter.** match t
33cc0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 han a function w
33cd0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
33ce0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 g is different.
33cf0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e .** ^A function
33d00 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
33d10 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
33d20 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c s between UTF16l
33d30 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a e and UTF16be.**
33d40 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 is a closer mat
33d50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
33d60 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
33d70 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
33d80 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 is.** between U
33d90 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a TF8 and UTF16..*
33da0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 *.** ^Built-in f
33db0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
33dc0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 overloaded by ne
33dd0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 w application-de
33de0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e fined functions.
33df0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 .**.** ^An appli
33e00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
33e10 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 unction is permi
33e20 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 tted to call oth
33e30 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
33e40 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 erfaces. Howeve
33e50 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 r, such calls mu
33e60 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 st not.** close
33e70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
33e80 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 nection nor fina
33e90 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 lize or reset th
33ea0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 e prepared.** st
33eb0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 atement in which
33ec0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
33ed0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c running..*/.SQL
33ee0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
33ef0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
33f00 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
33f10 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
33f20 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
33f30 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
33f40 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
33f50 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
33f60 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
33f70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
33f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
33f90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
33fa0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
33fb0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
33fc0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
33fd0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
33fe0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 3_context*).);.S
33ff0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
34000 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
34010 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ction16(. sqlit
34020 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
34030 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e void *zFunctionN
34040 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
34050 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
34060 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
34070 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
34080 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34090 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
340a0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
340b0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
340c0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
340d0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
340e0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
340f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
34100 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
34110 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
34120 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
34130 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
34140 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
34150 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
34160 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
34170 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
34180 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
34190 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
341a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
341b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
341c0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
341d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
341e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
341f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
34200 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
34210 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
34220 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
34230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34240 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
34250 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
34260 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
34270 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
34280 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
34290 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
342a0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
342b0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
342c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
342d0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
342e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
342f0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
34300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34310 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 UTF16BE 3
34320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
34330 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
34340 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
34350 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
34360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
34370 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
34380 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 /* sqlite3_cr
34390 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e eate_function on
343a0 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
343b0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e LITE_UTF16_ALIGN
343c0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 ED 8 /* sqli
343d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
343e0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a tion only */../*
343f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
34400 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
34410 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
34420 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
34430 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
34440 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
34450 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
34460 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
34470 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
34480 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
34490 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
344a0 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
344b0 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
344c0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
344d0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
344e0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
344f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
34500 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
34510 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
34520 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
34530 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
34540 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
34550 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 tell you what t
34560 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
34570 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
34580 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
34590 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
345a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
345b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
345c0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
345d0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 xt*);.SQLITE_API
345e0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
345f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
34600 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
34610 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 tmt*);.SQLITE_AP
34620 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
34630 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
34640 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 transfer_binding
34650 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
34660 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b sqlite3_stmt*);
34670 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
34680 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
34690 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
346a0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
346b0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
346c0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
346d0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
346e0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
346f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
34700 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
34710 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
34720 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f alarm(void(*)(vo
34730 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 id*,sqlite3_int6
34740 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 4,int),void*,sql
34750 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
34760 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
34770 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
34780 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 QL Function Para
34790 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a meter Values.**.
347a0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 ** The C-languag
347b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
347c0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e of SQL function
347d0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
347e0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 uses.** this se
347f0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 t of interface r
34800 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 outines to acces
34810 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 s the parameter
34820 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 values on.** the
34830 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
34840 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 regate..**.** Th
34850 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 e xFunc (for sca
34860 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f lar functions) o
34870 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 r xStep (for agg
34880 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 regates) paramet
34890 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 ers.** to [sqlit
348a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
348b0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
348c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
348d0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e on16()].** defin
348e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 e callbacks that
348f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
34900 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
34910 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 aggregates..**
34920 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 The 3rd paramete
34930 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 r to these callb
34940 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 acks is an array
34950 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a of pointers to.
34960 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 ** [protected sq
34970 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
34980 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 ects. There is
34990 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c one [sqlite3_val
349a0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a ue] object for.*
349b0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 * each parameter
349c0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 to the SQL func
349d0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 tion. These rou
349e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 tines are used t
349f0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c o.** extract val
34a00 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ues from the [sq
34a10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
34a20 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ects..**.** Thes
34a30 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
34a40 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 only with [prote
34a50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
34a60 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 ue] objects..**
34a70 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 Any attempt to u
34a80 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 se these routine
34a90 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 s on an [unprote
34aa0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
34ab0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 ue].** object re
34ac0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e sults in undefin
34ad0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a ed behavior..**.
34ae0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
34af0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b es work just lik
34b00 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 e the correspond
34b10 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 ing [column acce
34b20 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a ss functions].**
34b30 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 except that th
34b40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
34b50 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
34b60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34b70 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
34b80 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
34b90 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
34ba0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
34bb0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
34bc0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
34bd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
34be0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
34bf0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
34c00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
34c10 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
34c20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
34c30 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
34c40 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
34c50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
34c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
34c70 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
34c80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
34c90 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
34ca0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
34cb0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
34cc0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
34cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
34ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
34cf0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
34d00 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
34d10 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
34d20 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
34d30 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
34d40 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
34d50 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
34d60 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
34d70 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
34d80 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
34d90 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
34da0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
34db0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
34dc0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
34dd0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
34de0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
34df0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
34e00 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
34e10 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
34e20 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
34e30 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
34e40 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
34e50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
34e60 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
34e70 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
34e80 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
34e90 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
34ea0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
34eb0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
34ec0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
34ed0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
34ee0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
34ef0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
34f00 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
34f10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
34f20 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
34f30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34f40 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
34f50 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
34f60 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
34f70 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
34f80 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
34f90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34fa0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
34fb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
34fc0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
34fd0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
34fe0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
34ff0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
35000 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
35010 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
35020 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
35030 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
35040 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
35050 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
35060 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
35070 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
35080 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
35090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
350a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
350b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
350c0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
350d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
350e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
350f0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
35100 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
35110 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c E_API double sql
35120 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c ite3_value_doubl
35130 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
35140 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
35150 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
35160 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
35170 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
35180 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
35190 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 lite3_value_int6
351a0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 4(sqlite3_value*
351b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
351c0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
351d0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
351e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
351f0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
35200 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
35210 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
35220 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
35230 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
35240 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
35250 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
35260 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
35270 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
35280 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
35290 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
352a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
352b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
352c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
352d0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
352e0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
352f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
35300 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 e_numeric_type(s
35310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
35320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35330 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
35340 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
35350 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 xt.**.** Impleme
35360 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 ntations of aggr
35370 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
35380 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 ons use this.**
35390 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 routine to alloc
353a0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 ate memory for s
353b0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 toring their sta
353c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 te..**.** ^The f
353d0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 irst time the sq
353e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
353f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
35400 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a tine is called .
35410 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ** for a particu
35420 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 lar aggregate fu
35430 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a nction, SQLite.*
35440 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 * allocates N of
35450 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 memory, zeroes
35460 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c out that memory,
35470 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
35480 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
35490 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e new memory. ^On
354a0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
354b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a equent calls to.
354c0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 ** sqlite3_aggre
354d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 gate_context() f
354e0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 or the same aggr
354f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 egate function i
35500 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 nstance,.** the
35510 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 same buffer is r
35520 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 eturned. Sqlite
35530 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35540 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c ext() is normall
35550 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 y.** called once
35560 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 for each invoca
35570 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 tion of the xSte
35580 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 p callback and t
35590 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 hen one.** last
355a0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 time when the xF
355b0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 inal callback is
355c0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 invoked. ^(Whe
355d0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a n no rows match.
355e0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 ** an aggregate
355f0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 query, the xStep
35600 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 () callback of t
35610 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e he aggregate fun
35620 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ction.** impleme
35630 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 ntation is never
35640 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e called and xFin
35650 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 al() is called e
35660 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 xactly once..**
35670 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 In those cases,
35680 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
35690 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 e_context() migh
356a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 t be called for
356b0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d the.** first tim
356c0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 e from within xF
356d0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 inal().)^.**.**
356e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 ^The sqlite3_agg
356f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
35700 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ,N) routine retu
35710 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
35720 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 er if N is.** le
35730 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
35740 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
35750 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 memory allocate
35760 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a error occurs..*
35770 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e *.** ^(The amoun
35780 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 t of space alloc
35790 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
357a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
357b0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 t(C,N) is.** det
357c0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e ermined by the N
357d0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 parameter on fi
357e0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 rst successful c
357f0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 all. Changing t
35800 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e he.** value of N
35810 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
35820 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 all to sqlite3_a
35830 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
35840 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 () within.** the
35850 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 same aggregate
35860 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 function instanc
35870 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a e will not resiz
35880 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 e the memory.**
35890 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a allocation.)^.**
358a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f .** ^SQLite auto
358b0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
358c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
358d0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 ated by .** sqli
358e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
358f0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 ntext() when the
35900 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
35910 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
35920 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
35930 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 meter must be a
35940 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
35950 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
35960 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
35970 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
35980 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
35990 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 ter.** to the xS
359a0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 tep or xFinal ca
359b0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
359c0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
359d0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
359e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
359f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
35a00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
35a10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
35a20 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
35a30 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
35a40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
35a50 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
35a60 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
35a70 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
35a80 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
35a90 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b t*, int nBytes);
35aa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35ab0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 : User Data For
35ac0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
35ad0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 ^The sqlite3_use
35ae0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 r_data() interfa
35af0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
35b00 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e y of.** the poin
35b10 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 ter that was the
35b20 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d pUserData param
35b30 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 eter (the 5th pa
35b40 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
35b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
35b60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
35b70 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
35b80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
35b90 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
35ba0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
35bb0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
35bc0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
35bd0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ed function..**.
35be0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
35bf0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
35c00 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
35c10 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
35c20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
35c30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35c40 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a is running..*/.
35c50 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
35c60 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
35c70 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
35c80 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
35c90 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
35ca0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
35cb0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
35cc0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 The sqlite3_cont
35cd0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 ext_db_handle()
35ce0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
35cf0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
35d00 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
35d10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
35d20 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 ection] (the 1st
35d30 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
35d40 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
35d50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
35d60 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
35d70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35d80 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
35d90 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
35da0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
35db0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
35dc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
35dd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
35de0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 lite3 *sqlite3_c
35df0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
35e00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35e10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
35e20 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 REF: Function Au
35e30 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a xiliary Data.**.
35e40 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** The following
35e50 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d two functions m
35e60 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 ay be used by sc
35e70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
35e80 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 ns to.** associa
35e90 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 te metadata with
35ea0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 argument values
35eb0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 . If the same va
35ec0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f lue is passed to
35ed0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 .** multiple inv
35ee0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
35ef0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
35f00 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 n during query e
35f10 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a xecution, under.
35f20 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 ** some circumst
35f30 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 ances the associ
35f40 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 ated metadata ma
35f50 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 y be preserved.
35f60 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 This may.** be u
35f70 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 sed, for example
35f80 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c , to add a regul
35f90 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 ar-expression ma
35fa0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a tching scalar.**
35fb0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 function. The c
35fc0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 ompiled version
35fd0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 of the regular e
35fe0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f xpression is sto
35ff0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 red as.** metada
36000 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ta associated wi
36010 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 th the SQL value
36020 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 passed as the r
36030 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
36040 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 n.** pattern. T
36050 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 he compiled regu
36060 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
36070 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 an be reused on
36080 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f multiple.** invo
36090 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
360a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 ame function so
360b0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 that the origina
360c0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 l pattern string
360d0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 .** does not nee
360e0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c d to be recompil
360f0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 ed on each invoc
36100 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
36110 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 e sqlite3_get_au
36120 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
36130 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
36140 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 ter to the metad
36150 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
36160 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 d by the sqlite3
36170 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 _set_auxdata() f
36180 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 unction with the
36190 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a Nth argument.**
361a0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 value to the ap
361b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
361c0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 d function. ^If
361d0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 no metadata has
361e0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 been ever.** bee
361f0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 n set for the Nt
36200 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 h argument of th
36210 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 e function, or i
36220 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 f the correspond
36230 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
36240 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 parameter has ch
36250 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 anged since the
36260 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 meta-data was se
36270 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 t,.** then sqlit
36280 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
36290 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
362a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
362b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
362c0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
362d0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 ace saves the me
362e0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 tadata.** pointe
362f0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 d to by its 3rd
36300 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
36310 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
36320 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
36330 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
36340 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
36350 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 nction. Subsequ
36360 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ent.** calls to
36370 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
36380 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 ata() might retu
36390 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 rn this data, if
363a0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 it has.** not b
363b0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a een destroyed..*
363c0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 * ^If it is not
363d0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c NULL, SQLite wil
363e0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 l invoke the des
363f0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 tructor.** funct
36400 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 ion given by the
36410 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
36420 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
36430 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 xdata() on.** th
36440 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 e metadata when
36450 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
36460 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
36470 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 eter changes.**
36480 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 or when the SQL
36490 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 statement comple
364a0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 tes, whichever c
364b0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a omes first..**.*
364c0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 * SQLite is free
364d0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 to call the des
364e0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 tructor and drop
364f0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 metadata on any
36500 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 .** parameter of
36510 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 any function at
36520 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 any time. ^The
36530 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 only guarantee
36540 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 is that.** the d
36550 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 estructor will b
36560 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 e called before
36570 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
36580 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e dropped..**.** ^
36590 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 (In practice, me
365a0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 tadata is preser
365b0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 ved between func
365c0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a tion calls for.*
365d0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 * expressions th
365e0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 at are constant
365f0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
36600 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c This includes l
36610 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
36620 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 and [parameters
36630 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ].)^.**.** These
36640 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
36650 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
36660 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
36670 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 which.** the SQ
36680 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
36690 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
366a0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
366b0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
366c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
366d0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f int N);.SQLITE_
366e0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
366f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
36700 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
36710 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 nt N, void*, voi
36720 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a d (*)(void*));..
36730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36740 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e Constants Defin
36750 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 ing Special Dest
36760 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a ructor Behavior.
36770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 **.** These are
36780 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 special values f
36790 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f or the destructo
367a0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 r that is passed
367b0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 in as the.** fi
367c0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 nal argument to
367d0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 routines like [s
367e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
367f0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 ob()]. ^If the
36800 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 destructor.** ar
36810 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 gument is SQLITE
36820 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e _STATIC, it mean
36830 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
36840 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f nt pointer is co
36850 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 nstant.** and wi
36860 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e ll never change.
36870 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 It does not ne
36880 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 ed to be destroy
36890 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c ed. ^The.** SQL
368a0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 ITE_TRANSIENT va
368b0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 lue means that t
368c0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 he content will
368d0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e likely change in
368e0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 .** the near fut
368f0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c ure and that SQL
36900 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 ite should make
36910 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
36920 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
36930 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 ontent before re
36940 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 turning..**.** T
36950 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 he typedef is ne
36960 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 cessary to work
36970 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 around problems
36980 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b in certain.** C+
36990 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 + compilers. Se
369a0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a e ticket #2191..
369b0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 */.typedef void
369c0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 (*sqlite3_destru
369d0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a ctor_type)(void*
369e0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 );.#define SQLIT
369f0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 E_STATIC ((
36a00 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
36a10 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 or_type)0).#defi
36a20 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ne SQLITE_TRANSI
36a30 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f ENT ((sqlite3_
36a40 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
36a50 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 -1)../*.** CAPI3
36a60 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 REF: Setting The
36a70 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 Result Of An SQ
36a80 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a L Function.**.**
36a90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
36aa0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 are used by the
36ab0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 xFunc or xFinal
36ac0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a callbacks that.*
36ad0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 * implement SQL
36ae0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
36af0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a gregates. See.*
36b00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
36b10 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
36b20 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
36b30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
36b40 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ** for additiona
36b50 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
36b60 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
36b70 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d ions work very m
36b80 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 uch like the [pa
36b90 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d rameter binding]
36ba0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 family of.** fu
36bb0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 nctions used to
36bc0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 bind values to h
36bd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 ost parameters i
36be0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 n prepared state
36bf0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 ments..** Refer
36c00 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 to the [SQL para
36c10 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 meter] documenta
36c20 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f tion for additio
36c30 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
36c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36c50 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
36c60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
36c70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
36c80 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
36c90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36ca0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c ion to be the BL
36cb0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 OB whose content
36cc0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 is pointed.** t
36cd0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 o by the second
36ce0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 parameter and wh
36cf0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c ich is N bytes l
36d00 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 ong where N is t
36d10 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 he.** third para
36d20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
36d30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36d40 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 _zeroblob() inte
36d50 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 rfaces set the r
36d60 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
36d70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
36d80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
36d90 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 be a BLOB contai
36da0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a ning all zero.**
36db0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 bytes and N byt
36dc0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 es in size, wher
36dd0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 e N is the value
36de0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 of the 2nd para
36df0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 meter..**.** ^Th
36e00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
36e10 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 _double() interf
36e20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
36e30 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
36e40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
36e50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
36e60 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 e a floating poi
36e70 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 nt value specifi
36e80 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 ed.** by its 2nd
36e90 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
36ea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
36eb0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
36ec0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36ed0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 error16() functi
36ee0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 ons.** cause the
36ef0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c implemented SQL
36f00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 function to thr
36f10 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e ow an exception.
36f20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 .** ^SQLite uses
36f30 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e the string poin
36f40 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a ted to by the.**
36f50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
36f60 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 f sqlite3_result
36f70 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 _error() or sqli
36f80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36f90 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 16().** as the t
36fa0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ext of an error
36fb0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 message. ^SQLit
36fc0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 e interprets the
36fd0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 error.** messag
36fe0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 e string from sq
36ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37000 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e or() as UTF-8. ^
37010 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 SQLite.** interp
37020 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 rets the string
37030 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
37040 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 ult_error16() as
37050 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
37060 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e e.** byte order.
37070 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 ^If the third
37080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
37090 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
370a0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 r().** or sqlite
370b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
370c0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 () is negative t
370d0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
370e0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a as the error.**
370f0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 message all tex
37100 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 t up through the
37110 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
37120 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
37130 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
37140 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
37150 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a ult_error() or.*
37160 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
37170 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f _error16() is no
37180 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 n-negative then
37190 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 SQLite takes tha
371a0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 t many.** bytes
371b0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
371c0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 from the 2nd pa
371d0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 rameter as the e
371e0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
371f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
37200 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 sult_error() and
37210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37220 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 error16().** rou
37230 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 tines make a pri
37240 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
37250 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 error message t
37260 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ext before.** th
37270 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 ey return. Henc
37280 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 e, the calling f
37290 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c unction can deal
372a0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 locate or.** mod
372b0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 ify the text aft
372c0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 er they return w
372d0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 ithout harm..**
372e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
372f0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 ult_error_code()
37300 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 function change
37310 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 s the error code
37320 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
37330 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 SQLite as a resu
37340 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 lt of an error i
37350 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e n a function. ^
37360 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 By default,.** t
37370 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 he error code is
37380 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 SQLITE_ERROR.
37390 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ^A subsequent ca
373a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 ll to sqlite3_re
373b0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 sult_error().**
373c0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
373d0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 t_error16() rese
373e0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 ts the error cod
373f0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f e to SQLITE_ERRO
37400 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 R..**.** ^The sq
37410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
37420 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 or_toobig() inte
37430 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
37440 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a ite to throw an.
37450 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 ** error indicat
37460 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e ing that a strin
37470 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f g or BLOB is too
37480 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 long to represe
37490 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nt..**.** ^The s
374a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
374b0 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 ror_nomem() inte
374c0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c rface causes SQL
374d0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a ite to throw an.
374e0 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 ** error indicat
374f0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 ing that a memor
37500 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
37510 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
37520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
37530 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 nt() interface s
37540 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 ets the return v
37550 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 alue.** of the a
37560 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
37570 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
37580 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 e the 32-bit sig
37590 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 ned integer.** v
375a0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 alue given in th
375b0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a e 2nd argument..
375c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
375d0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 result_int64() i
375e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
375f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
37600 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
37610 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
37620 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
37630 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
37640 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
37650 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
37660 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
37670 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
37680 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 ult_null() inter
37690 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
376a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
376b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
376c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
376d0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a n to be NULL..**
376e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
376f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 _result_text(),
37700 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37710 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 ext16(),.** sqli
37720 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
37730 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 6le(), and sqlit
37740 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
37750 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a be() interfaces.
37760 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 ** set the retur
37770 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 n value of the a
37780 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
37790 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
377a0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 e.** a text stri
377b0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 ng which is repr
377c0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 esented as UTF-8
377d0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 , UTF-16 native
377e0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 byte order,.** U
377f0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 TF-16 little end
37800 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 ian, or UTF-16 b
37810 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 ig endian, respe
37820 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c ctively..** ^SQL
37830 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 ite takes the te
37840 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 xt result from t
37850 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 he application f
37860 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 rom.** the 2nd p
37870 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
37880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37890 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e ext* interfaces.
378a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 .** ^If the 3rd
378b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
378c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
378d0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
378e0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
378f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
37900 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 es result text f
37910 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
37920 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 meter.** through
37930 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 the first zero
37940 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 character..** ^I
37950 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
37960 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
37970 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
37980 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
37990 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
379a0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 hen as many byte
379b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s (not character
379c0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a s) of the text.*
379d0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
379e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
379f0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 r are taken as t
37a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
37a10 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 efined.** functi
37a20 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 on result. If t
37a30 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
37a40 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
37a50 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 , then it.** mus
37a60 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 t be the byte of
37a70 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 fset into the st
37a80 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e ring where the N
37a90 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f UL terminator wo
37aa0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 uld.** appear if
37ab0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 the string wher
37ac0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 e NUL terminated
37ad0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 . If any NUL ch
37ae0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a aracters occur.*
37af0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 * in the string
37b00 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 at a byte offset
37b10 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 that is less th
37b20 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 an the value of
37b30 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d the 3rd.** param
37b40 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 eter, then the r
37b50 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 esulting string
37b60 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 will contain emb
37b70 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 edded NULs and t
37b80 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 he.** result of
37b90 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 expressions oper
37ba0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 ating on strings
37bb0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e with embedded N
37bc0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ULs is undefined
37bd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
37be0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37bf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
37c00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
37c10 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
37c20 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 result_blob is a
37c30 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
37c40 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 r, then SQLite c
37c50 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e alls that.** fun
37c60 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 ction as the des
37c70 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 tructor on the t
37c80 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 ext or BLOB resu
37c90 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a lt when it has.*
37ca0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 * finished using
37cb0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
37cc0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
37cd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
37ce0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37cf0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 t* interfaces or
37d00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 to.** sqlite3_r
37d10 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
37d20 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
37d30 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 nt SQLITE_STATIC
37d40 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
37d50 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
37d60 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
37d70 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 esult is in cons
37d80 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 tant space and d
37d90 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 oes not.** copy
37da0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
37db0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 he parameter nor
37dc0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 call a destruct
37dd0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e or on the conten
37de0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 t.** when it has
37df0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
37e00 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
37e10 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
37e20 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
37e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
37e40 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
37e50 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c or sqlite3_resul
37e60 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
37e70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
37e80 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a QLITE_TRANSIENT.
37e90 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d ** then SQLite m
37ea0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
37eb0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 he result into s
37ec0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 pace obtained fr
37ed0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 om.** from [sqli
37ee0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 te3_malloc()] be
37ef0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e fore it returns.
37f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37f10 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
37f20 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
37f30 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a s the result of.
37f40 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
37f50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
37f60 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 ion to be a copy
37f70 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 the.** [unprote
37f80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
37f90 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 ue] object speci
37fa0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
37fb0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 parameter. ^The
37fc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
37fd0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 lt_value() inter
37fe0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 face makes a cop
37ff0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
38000 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 3_value].** so t
38010 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hat the [sqlite3
38020 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 _value] specifie
38030 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 d in the paramet
38040 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 er may change or
38050 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 .** be deallocat
38060 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ed after sqlite3
38070 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
38080 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 returns without
38090 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f harm..** ^A [pro
380a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
380b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 alue] object may
380c0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 always be used
380d0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 where an.** [unp
380e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
380f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 _value] object i
38100 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 s required, so e
38110 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 ither.** kind of
38120 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
38130 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 object can be u
38140 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e sed with this in
38150 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 terface..**.** I
38160 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
38170 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
38180 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 within the diff
38190 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 erent thread.**
381a0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e than the one con
381b0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c taining the appl
381c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
381d0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 function that re
381e0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 ceived.** the [s
381f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
38200 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 pointer, the res
38210 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
38220 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ed..*/.SQLITE_AP
38230 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
38240 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
38250 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
38260 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
38270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
38280 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
38290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
382a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f ouble(sqlite3_co
382b0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b ntext*, double);
382c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
382d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
382e0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f error(sqlite3_co
382f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
38300 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 ar*, int);.SQLIT
38310 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
38320 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
38330 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
38340 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
38350 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
38360 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
38370 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 esult_error_toob
38380 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ig(sqlite3_conte
38390 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 xt*);.SQLITE_API
383a0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
383b0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d sult_error_nomem
383c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
383d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
383e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
383f0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 lt_error_code(sq
38400 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
38410 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
38420 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 void sqlite3_re
38430 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
38440 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
38450 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
38460 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38470 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
38480 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
38490 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
384a0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
384b0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
384c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
384d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
384e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
384f0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
38500 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
38510 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
38520 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
38530 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
38540 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 result_text16(sq
38550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
38560 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
38570 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
38580 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
38590 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
385a0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 t_text16le(sqlit
385b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
385c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
385d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
385e0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
385f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38600 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 xt16be(sqlite3_c
38610 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
38620 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
38630 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
38640 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
38650 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
38660 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38670 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
38680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
38690 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
386a0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
386b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
386c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
386d0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
386e0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
386f0 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 nces.**.** ^Thes
38700 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c e functions add,
38710 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 remove, or modi
38720 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d fy a [collation]
38730 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
38740 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
38750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
38760 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 ecified as the f
38770 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
38780 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
38790 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 f the collation
387a0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
387b0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
387c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _