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 32 2e 20 20 ersion 3.7.12.
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 4d 45 4d * SQLITE_MEM
3480: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 DEBUG
3490: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 // Debugging
34a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 version of syst
34b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a em malloc().**.*
34c0: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 * On Windows, if
34d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 the SQLITE_WIN3
34e0: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 2_MALLOC_VALIDAT
34f0: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e E macro is defin
3500: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 ed and the.** as
3510: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 sert() macro is
3520: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 enabled, each ca
3530: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 ll into the Win3
3540: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 2 native heap su
3550: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 bsystem.** will
3560: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 cause HeapValida
3570: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e te to be called.
3580: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 If heap valida
3590: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c tion should fail
35a0: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f , an.** assertio
35b0: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 n will be trigge
35c0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 red..**.** (Hist
35d0: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 orical note: Th
35e0: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 ere used to be s
35f0: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 everal other opt
3600: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a ions, but we've.
3610: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e ** pared it down
3620: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 to just these t
3630: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 hree.).**.** If
3640: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 none of the abov
3650: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 e are defined, t
3660: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 hen set SQLITE_S
3670: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a YSTEM_MALLOC as.
3680: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a ** the default..
3690: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 */.#if defined(S
36a0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c QLITE_SYSTEM_MAL
36b0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c LOC)+defined(SQL
36c0: 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 ITE_WIN32_MALLOC
36d0: 29 2b 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 )+defined(SQLITE
36e0: 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 _MEMDEBUG)>1.# e
36f0: 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e rror "At most on
3700: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
3710: 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ng compile-time
3720: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
3730: 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77 tions\. is allow
3740: 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d s: SQLITE_SYSTEM
3750: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f _MALLOC, SQLITE_
3760: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 WIN32_MALLOC, SQ
3770: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 22 0a 23 LITE_MEMDEBUG".#
3780: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 endif.#if define
3790: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f d(SQLITE_SYSTEM_
37a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 MALLOC)+defined(
37b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c SQLITE_WIN32_MAL
37c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c LOC)+defined(SQL
37d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30 ITE_MEMDEBUG)==0
37e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
37f0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31 _SYSTEM_MALLOC 1
3800: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 .#endif../*.** I
3810: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f f SQLITE_MALLOC_
3820: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f SOFT_LIMIT is no
3830: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79 t zero, then try
3840: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20 to keep the.**
3850: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 sizes of memory
3860: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f allocations belo
3870: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65 w this value whe
3880: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a re possible..*/.
3890: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c #if !defined(SQL
38a0: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f ITE_MALLOC_SOFT_
38b0: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20 LIMIT).# define
38c0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f SQLITE_MALLOC_SO
38d0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65 FT_LIMIT 1024.#e
38e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e ndif../*.** We n
38f0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58 eed to define _X
3900: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66 OPEN_SOURCE as f
3910: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20 ollows in order
3920: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63 to enable.** rec
3930: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f ursive mutexes o
3940: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74 n most Unix syst
3950: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53 ems. But Mac OS
3960: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e X is different.
3970: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53 .** The _XOPEN_S
3980: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75 OURCE define cau
3990: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72 ses problems for
39a0: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65 Mac OS X we are
39b0: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20 told,.** so it
39c0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65 is omitted there
39d0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
39e0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72 673..**.** Later
39f0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f we learn that _
3a00: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20 XOPEN_SOURCE is
3a10: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72 poorly or incorr
3a20: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65 ectly.** impleme
3a30: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73 nted on some sys
3a40: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f tems. So we avo
3a50: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61 id defining it a
3a60: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69 t all.** if it i
3a70: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65 s already define
3a80: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e d or if it is un
3a90: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77 needed because w
3aa0: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69 e are.** not doi
3ab0: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20 ng a threadsafe
3ac0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23 build. Ticket #
3ad0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 2681..**.** See
3ae0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34 also ticket #274
3af0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 1..*/.#if !defin
3b00: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 ed(_XOPEN_SOURCE
3b10: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f ) && !defined(__
3b20: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65 DARWIN__) && !de
3b30: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29 fined(__APPLE__)
3b40: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41 && SQLITE_THREA
3b50: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20 DSAFE.# define
3b60: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30 _XOPEN_SOURCE 50
3b70: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20 0 /* Needed to
3b80: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72 enable pthread r
3b90: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 ecursive mutexes
3ba0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a */.#endif../*.*
3bb0: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72 * The TCL header
3bc0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65 s are only neede
3bd0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 d when compiling
3be0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67 the TCL binding
3bf0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 s..*/.#if define
3c00: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c d(SQLITE_TCL) ||
3c10: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a defined(TCLSH).
3c20: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68 # include <tcl.h
3c30: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 >.#endif../*.**
3c40: 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61 72 65 20 Many people are
3c50: 66 61 69 6c 69 6e 67 20 74 6f 20 73 65 74 20 2d failing to set -
3c60: 44 4e 44 45 42 55 47 3d 31 20 77 68 65 6e 20 63 DNDEBUG=1 when c
3c70: 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69 74 65 2e ompiling SQLite.
3c80: 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e 44 45 42 .** Setting NDEB
3c90: 55 47 20 6d 61 6b 65 73 20 74 68 65 20 63 6f 64 UG makes the cod
3ca0: 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20 72 75 e smaller and ru
3cb0: 6e 20 66 61 73 74 65 72 2e 20 20 53 6f 20 74 68 n faster. So th
3cc0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 6c e following.** l
3cd0: 69 6e 65 73 20 61 72 65 20 61 64 64 65 64 20 74 ines are added t
3ce0: 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 o automatically
3cf0: 73 65 74 20 4e 44 45 42 55 47 20 75 6e 6c 65 73 set NDEBUG unles
3d00: 73 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 s the -DSQLITE_D
3d10: 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74 69 6f 6e EBUG=1.** option
3d20: 20 69 73 20 73 65 74 2e 20 20 54 68 75 73 20 4e is set. Thus N
3d30: 44 45 42 55 47 20 62 65 63 6f 6d 65 73 20 61 6e DEBUG becomes an
3d40: 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 72 20 74 opt-in rather t
3d50: 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a han an opt-out.*
3d60: 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 * feature..*/.#i
3d70: 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55 f !defined(NDEBU
3d80: 47 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 G) && !defined(S
3d90: 51 4c 49 54 45 5f 44 45 42 55 47 29 20 0a 23 20 QLITE_DEBUG) .#
3da0: 64 65 66 69 6e 65 20 4e 44 45 42 55 47 20 31 0a define NDEBUG 1.
3db0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 #endif../*.** Th
3dc0: 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 e testcase() mac
3dd0: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69 ro is used to ai
3de0: 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65 d in coverage te
3df0: 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a sting. When .**
3e00: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 doing coverage
3e10: 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e testing, the con
3e20: 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 dition inside th
3e30: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a e argument to.**
3e40: 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74 testcase() must
3e50: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f be evaluated bo
3e60: 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 th true and fals
3e70: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a e in order to.**
3e80: 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 get full branch
3e90: 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20 coverage. The
3ea0: 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f testcase() macro
3eb0: 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 is inserted.**
3ec0: 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61 to help ensure a
3ed0: 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76 dequate test cov
3ee0: 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20 erage in places
3ef0: 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 where simple.**
3f00: 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 condition/decisi
3f10: 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69 on coverage is i
3f20: 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20 nadequate. For
3f30: 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 example, testcas
3f40: 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 e().** can be us
3f50: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 ed to make sure
3f60: 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20 boundary values
3f70: 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72 are tested. For
3f80: 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74 .** bitmask test
3f90: 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61 s, testcase() ca
3fa0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b n be used to mak
3fb0: 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a e sure each bit.
3fc0: 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e ** is significan
3fd0: 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65 t and used at le
3fe0: 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 ast once. On sw
3ff0: 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a itch statements.
4000: 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c ** where multipl
4010: 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68 e cases go to th
4020: 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 e same block of
4030: 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29 code, testcase()
4040: 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74 .** can insure t
4050: 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72 hat all cases ar
4060: 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a e evaluated..**.
4070: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
4080: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53 _COVERAGE_TEST.S
4090: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20 QLITE_PRIVATE
40a0: 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65 void sqlite3Cove
40b0: 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 rage(int);.# def
40c0: 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20 ine testcase(X)
40d0: 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65 if( X ){ sqlite
40e0: 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 3Coverage(__LINE
40f0: 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 __); }.#else.# d
4100: 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 efine testcase(X
4110: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ).#endif../*.**
4120: 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 The TESTONLY mac
4130: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e ro is used to en
4140: 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64 close variable d
4150: 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a eclarations or.*
4160: 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20 * other bits of
4170: 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65 code that are ne
4180: 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 eded to support
4190: 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a the arguments.**
41a0: 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65 within testcase
41b0: 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20 () and assert()
41c0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 macros..*/.#if !
41d0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 defined(NDEBUG)
41e0: 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 || defined(SQLIT
41f0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29 E_COVERAGE_TEST)
4200: 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e .# define TESTON
4210: 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 LY(X) X.#else.#
4220: 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 define TESTONLY
4230: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a (X).#endif../*.*
4240: 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e * Sometimes we n
4250: 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 eed a small amou
4260: 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20 nt of code such
4270: 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e as a variable in
4280: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 itialization.**
4290: 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c to setup for a l
42a0: 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74 ater assert() st
42b0: 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 atement. We do
42c0: 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f not want this co
42d0: 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 de to.** appear
42e0: 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73 when assert() is
42f0: 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 disabled. The
4300: 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 following macro
4310: 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 is therefore.**
4320: 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 used to contain
4330: 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e that setup code.
4340: 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f The "VVA" acro
4350: 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a nym stands for.*
4360: 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c * "Verification,
4370: 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 Validation, and
4380: 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e Accreditation".
4390: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
43a0: 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 , the.** code wi
43b0: 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 thin VVA_ONLY()
43c0: 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 will only run du
43d0: 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f ring verificatio
43e0: 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a n processes..*/.
43f0: 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 #ifndef NDEBUG.#
4400: 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 define VVA_ONLY
4410: 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 (X) X.#else.# d
4420: 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 efine VVA_ONLY(X
4430: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 ).#endif../*.**
4440: 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e The ALWAYS and N
4450: 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72 EVER macros surr
4460: 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 ound boolean exp
4470: 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a ressions which .
4480: 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 ** are intended
4490: 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 to always be tru
44a0: 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70 e or false, resp
44b0: 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a ectively. Such.
44c0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 ** expressions c
44d0: 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20 ould be omitted
44e0: 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f from the code co
44f0: 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74 mpletely. But t
4500: 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 hey.** are inclu
4510: 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73 ded in a few cas
4520: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 es in order to e
4530: 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c nhance the resil
4540: 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 ience.** of SQLi
4550: 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64 te to unexpected
4560: 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d behavior - to m
4570: 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65 ake the code "se
4580: 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f lf-healing".** o
4590: 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68 r "ductile" rath
45a0: 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62 er than being "b
45b0: 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73 rittle" and cras
45c0: 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73 hing at the firs
45d0: 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 t.** hint of unp
45e0: 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e lanned behavior.
45f0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
4600: 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e words, ALWAYS an
4610: 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65 d NEVER are adde
4620: 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20 d for defensive
4630: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e code..**.** When
4640: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 doing coverage
4650: 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61 testing ALWAYS a
4660: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72 nd NEVER are har
4670: 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 d-coded to.** be
4680: 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 true and false
4690: 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65 so that the unre
46a0: 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65 achable code the
46b0: 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a n specify will.*
46c0: 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 * not be counted
46d0: 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64 as untested cod
46e0: 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 e..*/.#if define
46f0: 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 d(SQLITE_COVERAG
4700: 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65 E_TEST).# define
4710: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 ALWAYS(X)
4720: 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 (1).# define NEV
4730: 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a ER(X) (0).
4740: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e #elif !defined(N
4750: 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20 DEBUG).# define
4760: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 ALWAYS(X) (
4770: 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29 (X)?1:(assert(0)
4780: 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 ,0)).# define NE
4790: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58 VER(X) ((X
47a0: 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a )?(assert(0),1):
47b0: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 0).#else.# defin
47c0: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 e ALWAYS(X)
47d0: 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 (X).# define NE
47e0: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29 VER(X) (X)
47f0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 .#endif../*.** R
4800: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d eturn true (non-
4810: 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70 zero) if the inp
4820: 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20 ut is a integer
4830: 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 that is too larg
4840: 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 e.** to fit in 3
4850: 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61 2-bits. This ma
4860: 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69 cro is used insi
4870: 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65 de of various te
4880: 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 stcase().** macr
4890: 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 os to verify tha
48a0: 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64 t we have tested
48b0: 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 SQLite for larg
48c0: 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a e-file support..
48d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49 */.#define IS_BI
48e0: 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26 G_INT(X) (((X)&
48f0: 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66 ~(i64)0xffffffff
4900: 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 )!=0)../*.** The
4910: 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 macro unlikely(
4920: 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74 ) is a hint that
4930: 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f surrounds a boo
4940: 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 lean.** expressi
4950: 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c on that is usual
4960: 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f ly false. Macro
4970: 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 likely() surrou
4980: 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e nds.** a boolean
4990: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 expression that
49a0: 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65 is usually true
49b0: 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74 . GCC is able t
49c0: 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68 o.** use these h
49d0: 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65 ints to generate
49e0: 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f better code, so
49f0: 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 metimes..*/.#if
4a00: 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f defined(__GNUC__
4a10: 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20 ) && 0.# define
4a20: 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 likely(X) __b
4a30: 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 uiltin_expect((X
4a40: 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e ),1).# define un
4a50: 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 likely(X) __bui
4a60: 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c ltin_expect((X),
4a70: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 0).#else.# defin
4a80: 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21 e likely(X) !
4a90: 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e !(X).# define un
4aa0: 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29 likely(X) !!(X)
4ab0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a .#endif../******
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 ******** Include
4ad0: 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 sqlite3.h in th
4ae0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 e middle of sqli
4af0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a teInt.h ********
4b00: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a *******/./******
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 ******** Begin f
4b20: 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a ile sqlite3.h **
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4b50: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 *******/./*.** 2
4b60: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35 001 September 15
4b70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
4b80: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
4b90: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
4ba0: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
4bb0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
4bc0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
4bd0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
4be0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
4bf0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
4c00: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
4c10: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
4c20: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
4c30: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
4c40: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
4c50: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
4c60: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
4c70: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
4c80: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4cc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
4cd0: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
4ce0: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
4cf0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
4d00: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
4d10: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
4d20: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
4d30: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
4d40: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
4d50: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
4d60: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
4d70: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
4d80: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
4d90: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
4da0: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
4db0: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
4dc0: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
4dd0: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
4de0: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
4df0: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
4e00: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
4e10: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
4e20: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
4e30: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
4e40: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
4e50: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
4e60: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
4e70: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
4e80: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
4e90: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
4ea0: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
4eb0: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
4ec0: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
4ed0: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
4ee0: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
4ef0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
4f00: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
4f10: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
4f20: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
4f30: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
4f40: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
4f50: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
4f60: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
4f70: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
4f80: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
4f90: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
4fa0: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
4fb0: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
4fc0: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
4fd0: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
4fe0: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
4ff0: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
5000: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
5010: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
5020: 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 re suppose to op
5030: 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 erate..**.** The
5040: 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 name of this fi
5050: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 le under configu
5060: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
5070: 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 t is "sqlite.h.i
5080: 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 n"..** The makef
5090: 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d ile makes some m
50a0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 inor changes to
50b0: 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 this file (such
50c0: 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 as inserting.**
50d0: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 the version numb
50e0: 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 er) and changes
50f0: 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c its name to "sql
5100: 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 ite3.h" as.** pa
5110: 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 rt of the build
5120: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e process..*/.#ifn
5130: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a def _SQLITE3_H_.
5140: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 #define _SQLITE3
5150: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 _H_.#include <st
5160: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e darg.h> /* N
5170: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 eeded for the de
5180: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c finition of va_l
5190: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 ist */../*.** Ma
51a0: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 ke sure we can c
51b0: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 all this stuff f
51c0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 rom C++..*/.#if
51d0: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 0.extern "C" {.#
51e0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 endif.../*.** Ad
51f0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f d the ability to
5200: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 override 'exter
5210: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 n'.*/.#ifndef SQ
5220: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 LITE_EXTERN.# de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 fine SQLITE_EXTE
5240: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 RN extern.#endif
5250: 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 ..#ifndef SQLITE
5260: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 _API.# define SQ
5270: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a LITE_API.#endif.
5280: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f ../*.** These no
5290: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 -op macros are u
52a0: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 sed in front of
52b0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 interfaces to ma
52c0: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 rk those.** inte
52d0: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 rfaces as either
52e0: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 deprecated or e
52f0: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 xperimental. Ne
5300: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a w applications.*
5310: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 * should not use
5320: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 deprecated inte
5330: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 rfaces - they ar
5340: 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 e support for ba
5350: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
5360: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 tibility only.
5370: 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 Application writ
5380: 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 ers should be aw
5390: 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 are that.** expe
53a0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 rimental interfa
53b0: 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 ces are subject
53c0: 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 to change in poi
53d0: 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a nt releases..**.
53e0: 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 ** These macros
53f0: 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 used to resolve
5400: 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 to various kinds
5410: 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 of compiler mag
5420: 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 ic that.** would
5430: 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e generate warnin
5440: 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 g messages when
5450: 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 they were used.
5460: 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d But that.** com
5470: 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 piler magic ende
5480: 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 d up generating
5490: 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 such a flurry of
54a0: 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 bug reports.**
54b0: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b that we have tak
54c0: 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e en it all out an
54d0: 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 d gone back to u
54e0: 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e sing simple.** n
54f0: 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 oop macros..*/.#
5500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
5510: 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 PRECATED.#define
5520: 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 SQLITE_EXPERIME
5530: 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 NTAL../*.** Ensu
5540: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 re these symbols
5550: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 were not define
5560: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f d by some previo
5570: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a us header file..
5580: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
5590: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 _VERSION.# undef
55a0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a SQLITE_VERSION.
55b0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
55c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
55d0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 BER.# undef SQLI
55e0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
55f0: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 R.#endif../*.**
5600: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
5610: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 e-Time Library V
5620: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a ersion Numbers.*
5630: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 *.** ^(The [SQLI
5640: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 TE_VERSION] C pr
5650: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
5660: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e in the sqlite3.
5670: 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c h header.** eval
5680: 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e uates to a strin
5690: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 g literal that i
56a0: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 s the SQLite ver
56b0: 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 sion in the.** f
56c0: 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 ormat "X.Y.Z" wh
56d0: 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a ere X is the maj
56e0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
56f0: 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a r (always 3 for.
5700: 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 ** SQLite3) and
5710: 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 Y is the minor v
5720: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e ersion number an
5730: 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 d Z is the relea
5740: 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 se number.)^.**
5750: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 ^(The [SQLITE_VE
5760: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 RSION_NUMBER] C
5770: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
5780: 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 ro resolves to a
5790: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 n integer.** wit
57a0: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 h the value (X*1
57b0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 000000 + Y*1000
57c0: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c + Z) where X, Y,
57d0: 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 and Z are the s
57e0: 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 ame.** numbers u
57f0: 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 sed in [SQLITE_V
5800: 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 ERSION].)^.** Th
5810: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
5820: 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 _NUMBER for any
5830: 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 given release of
5840: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 SQLite will als
5850: 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 o.** be larger t
5860: 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 han the release
5870: 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 from which it is
5880: 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 derived. Eithe
5890: 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 r Y will.** be h
58a0: 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 eld constant and
58b0: 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 Z will be incre
58c0: 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 mented or else Y
58d0: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 will be increme
58e0: 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 nted.** and Z wi
58f0: 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a ll be reset to z
5900: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 ero..**.** Since
5910: 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c version 3.6.18,
5920: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 SQLite source c
5930: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f ode has been sto
5940: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 red in the.** <a
5950: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 href="http://ww
5960: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 w.fossil-scm.org
5970: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 /">Fossil config
5980: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
5990: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e nt.** system</a>
59a0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 . ^The SQLITE_S
59b0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 OURCE_ID macro e
59c0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 valuates to.** a
59d0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 string which id
59e0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 entifies a parti
59f0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f cular check-in o
5a00: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 f SQLite.** with
5a10: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 in its configura
5a20: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 tion management
5a30: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 system. ^The SQ
5a40: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a LITE_SOURCE_ID.*
5a50: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
5a60: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 s the date and t
5a70: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b ime of the check
5a80: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e -in (UTC) and an
5a90: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 SHA1.** hash of
5aa0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 the entire sour
5ab0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 ce tree..**.** S
5ac0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
5ad0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 3_libversion()],
5ae0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 .** [sqlite3_lib
5af0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
5b00: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 ], [sqlite3_sour
5b10: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ceid()],.** [sql
5b20: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
5b30: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
5b40: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 e_id()]..*/.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
5b60: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31 ON "3.7.1
5b70: 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2".#define SQLIT
5b80: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
5b90: 20 33 30 30 37 30 31 32 0a 23 64 65 66 69 6e 65 3007012.#define
5ba0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 SQLITE_SOURCE_I
5bb0: 44 20 20 20 20 20 20 22 32 30 31 32 2d 30 35 2d D "2012-05-
5bc0: 31 32 20 31 38 3a 32 39 3a 35 33 20 65 35 33 36 12 18:29:53 e536
5bd0: 61 63 30 34 31 38 31 35 62 31 31 38 63 34 36 31 ac041815b118c461
5be0: 63 65 65 65 37 39 38 66 39 62 37 32 38 33 32 36 ceee798f9b728326
5bf0: 39 66 35 38 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 9f58"../*.** CAP
5c00: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 I3REF: Run-Time
5c10: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 Library Version
5c20: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f Numbers.** KEYWO
5c30: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 RDS: sqlite3_ver
5c40: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f sion, sqlite3_so
5c50: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 urceid.**.** The
5c60: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 se interfaces pr
5c70: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 ovide the same i
5c80: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 nformation as th
5c90: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f e [SQLITE_VERSIO
5ca0: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 N],.** [SQLITE_V
5cb0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 ERSION_NUMBER],
5cc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 and [SQLITE_SOUR
5cd0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 CE_ID] C preproc
5ce0: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 essor macros.**
5cf0: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 but are associat
5d00: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 ed with the libr
5d10: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ary instead of t
5d20: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 he header file.
5d30: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 ^(Cautious.** p
5d40: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
5d50: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 include assert(
5d60: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 ) statements in
5d70: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f their applicatio
5d80: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 n to.** verify t
5d90: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 hat values retur
5da0: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 ned by these int
5db0: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 erfaces match th
5dc0: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 e macros in.** t
5dd0: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 he header, and t
5de0: 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 hus insure that
5df0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
5e00: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 is.** compiled w
5e10: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 ith matching lib
5e20: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 rary and header
5e30: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c files..**.** <bl
5e40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
5e50: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 * assert( sqlite
5e60: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
5e70: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 ber()==SQLITE_VE
5e80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a RSION_NUMBER );.
5e90: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d ** assert( strcm
5ea0: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 p(sqlite3_source
5eb0: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 id(),SQLITE_SOUR
5ec0: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 CE_ID)==0 );.**
5ed0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
5ee0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
5ef0: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 n(),SQLITE_VERSI
5f00: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 ON)==0 );.** </p
5f10: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
5f20: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
5f30: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 lite3_version[]
5f40: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 string constant
5f50: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 contains the tex
5f60: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 t of [SQLITE_VER
5f70: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 SION].** macro.
5f80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 ^The sqlite3_li
5f90: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 bversion() funct
5fa0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f ion returns a po
5fb0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 inter to the.**
5fc0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 to the sqlite3_v
5fd0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 ersion[] string
5fe0: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 constant. The s
5ff0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
6000: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 n().** function
6010: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 is provided for
6020: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 use in DLLs sinc
6030: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 e DLL users usua
6040: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a lly do not have.
6050: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 ** direct access
6060: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 to string const
6070: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 ants within the
6080: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 DLL. ^The.** sq
6090: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
60a0: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 _number() functi
60b0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e on returns an in
60c0: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a teger equal to.*
60d0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f * [SQLITE_VERSIO
60e0: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 N_NUMBER]. ^The
60f0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 sqlite3_sourcei
6100: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 d() function ret
6110: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 urns .** a point
6120: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 er to a string c
6130: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 onstant whose va
6140: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 lue is the same
6150: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 as the .** [SQLI
6160: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 TE_SOURCE_ID] C
6170: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
6180: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ro..**.** See al
6190: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 so: [sqlite_vers
61a0: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
61b0: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e te_source_id()].
61c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
61d0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 onst char sqlite
61e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 3_version[] = SQ
61f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 LITE_VERSION;.SQ
6200: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
6210: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 har *sqlite3_lib
6220: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 version(void);.S
6230: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
6240: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f char *sqlite3_so
6250: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 urceid(void);.SQ
6260: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
6270: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
6280: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f number(void);../
6290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
62a0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
62b0: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 Compilation Opti
62c0: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a ons Diagnostics.
62d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
62e0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
62f0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e _used() function
6300: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 returns 0 or 1
6310: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 .** indicating w
6320: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 hether the speci
6330: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 fied option was
6340: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 defined at .** c
6350: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 ompile time. ^T
6360: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 he SQLITE_ prefi
6370: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 x may be omitted
6380: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 from the .** op
6390: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 tion name passed
63a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to sqlite3_comp
63b0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
63c0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 . .**.** ^The s
63d0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
63e0: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 tion_get() funct
63f0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 ion allows itera
6400: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 ting.** over the
6410: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 list of options
6420: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e that were defin
6430: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 ed at compile ti
6440: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 me by.** returni
6450: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 ng the N-th comp
6460: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile time option
6470: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 string. ^If N i
6480: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a s out of range,.
6490: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 ** sqlite3_compi
64a0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 leoption_get() r
64b0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
64c0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c inter. ^The SQL
64d0: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 ITE_ .** prefix
64e0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
64f0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 any strings retu
6500: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 rned by .** sqli
6510: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
6520: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e n_get()..**.** ^
6530: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 Support for the
6540: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 diagnostic funct
6550: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d ions sqlite3_com
6560: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
6570: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 ).** and sqlite3
6580: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
6590: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 et() may be omit
65a0: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e ted by specifyin
65b0: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 g the .** [SQLIT
65c0: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 E_OMIT_COMPILEOP
65d0: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 TION_DIAGS] opti
65e0: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 on at compile ti
65f0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c me..**.** See al
6600: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e so: SQL function
6610: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c s [sqlite_compil
6620: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 eoption_used()]
6630: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 and.** [sqlite_c
6640: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
6650: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d ()] and the [com
6660: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 pile_options pra
6670: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 gma]..*/.#ifndef
6680: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d SQLITE_OMIT_COM
6690: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 PILEOPTION_DIAGS
66a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
66b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
66c0: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 ption_used(const
66d0: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 char *zOptName)
66e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
66f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
6710: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 et(int N);.#endi
6720: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
6730: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 F: Test To See I
6740: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 f The Library Is
6750: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a Threadsafe.**.*
6760: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
6770: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
6780: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 tion returns zer
6790: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 o if and only if
67a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 .** SQLite was c
67b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 ompiled with mut
67c0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 exing code omitt
67d0: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a ed due to the.**
67e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
67f0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AFE] compile-tim
6800: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 e option being s
6810: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 et to 0..**.** S
6820: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d QLite can be com
6830: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 piled with or wi
6840: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 thout mutexes.
6850: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c When.** the [SQL
6860: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
6870: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
6880: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 acro is 1 or 2,
6890: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
68a0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 nabled and SQLit
68b0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e e is threadsafe.
68c0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 When the.** [S
68d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
68e0: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a ] macro is 0, .*
68f0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 * the mutexes ar
6900: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 e omitted. With
6910: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c out the mutexes,
6920: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a it is not safe.
6930: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 ** to use SQLite
6940: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 concurrently fr
6950: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 om more than one
6960: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 thread..**.** E
6970: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 nabling mutexes
6980: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 incurs a measura
6990: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ble performance
69a0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 penalty..** So i
69b0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 f speed is of ut
69c0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c most importance,
69d0: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 it makes sense
69e0: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 to disable.** th
69f0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 e mutexes. But
6a00: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 for maximum safe
6a10: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ty, mutexes shou
6a20: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a ld be enabled..*
6a30: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
6a40: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d ehavior is for m
6a50: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 utexes to be ena
6a60: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 bled..**.** This
6a70: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
6a80: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 e used by an app
6a90: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 lication to make
6aa0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a sure that the.*
6ab0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c * version of SQL
6ac0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c ite that it is l
6ad0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 inking against w
6ae0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
6af0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 .** the desired
6b00: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b setting of the [
6b10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
6b20: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 E] macro..**.**
6b30: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f This interface o
6b40: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 nly reports on t
6b50: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
6b60: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a mutex setting.**
6b70: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
6b80: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 THREADSAFE] flag
6b90: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
6ba0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
6bb0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
6bc0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 FE=1 or =2 then
6bd0: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
6be0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
6bf0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
6c00: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
6c10: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
6c20: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
6c30: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
6c40: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
6c50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
6c60: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
6c70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
6c80: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
6c90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
6ca0: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 TEX]. ^(The ret
6cb0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
6cc0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 .** sqlite3_thre
6cd0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
6ce0: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 n shows only the
6cf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 compile-time se
6d00: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 tting of.** thre
6d10: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 ad safety, not a
6d20: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
6d30: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 ges to that sett
6d40: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 ing made by.** s
6d50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e qlite3_config().
6d60: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
6d70: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
6d80: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 e from sqlite3_t
6d90: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 hreadsafe().** i
6da0: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 s unchanged by c
6db0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
6dc0: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a config().)^.**.*
6dd0: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 * See the [threa
6de0: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d ding mode] docum
6df0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
6e00: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
6e10: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
6e20: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
6e30: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b hreadsafe(void);
6e40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6e50: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
6e60: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 ction Handle.**
6e70: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 KEYWORDS: {datab
6e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 ase connection}
6e90: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
6ea0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 tions}.**.** Eac
6eb0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 h open SQLite da
6ec0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 tabase is repres
6ed0: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 ented by a point
6ee0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
6ef0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 e of.** the opaq
6f00: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d ue structure nam
6f10: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 ed "sqlite3". I
6f20: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 t is useful to t
6f30: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 hink of an sqlit
6f40: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 e3.** pointer as
6f50: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 an object. The
6f60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
6f70: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
6f80: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 16()], and.** [s
6f90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
6fa0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ] interfaces are
6fb0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 its constructor
6fc0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f s, and [sqlite3_
6fd0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 close()].** is i
6fe0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 ts destructor.
6ff0: 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f There are many o
7000: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 ther interfaces
7010: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
7020: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
7030: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
7040: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
7050: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
7060: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
7070: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
7080: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
7090: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
70a0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
70b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
70c0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
70d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
70e0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
70f0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
7100: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
7110: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
7120: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
7130: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
7140: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
7150: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
7160: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
7170: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
7180: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
7190: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
71a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
71b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
71c0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
71d0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
71e0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
71f0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
7200: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
7210: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
7220: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
7230: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
7240: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
7250: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
7260: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
7270: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
7280: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
7290: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
72a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
72b0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
72c0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
72d0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
72e0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
72f0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
7300: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
7310: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
7320: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
7330: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
7340: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
7350: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
7360: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
7370: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
7380: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
7390: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
73a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
73b0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
73c0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
73d0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
73e0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 ;.#elif defined(
73f0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
7400: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
7410: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
7420: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
7430: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
7440: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
7450: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
7460: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
7470: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
7480: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
7490: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
74a0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
74b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
74c0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
74d0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
74e0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
74f0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
7500: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
7510: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
7520: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
7530: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
7540: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
7550: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
7560: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
7570: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
7580: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
7590: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
75a0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
75b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
75c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
75d0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
75e0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
75f0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ion.**.** ^The s
7600: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 qlite3_close() r
7610: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 outine is the de
7620: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 structor for the
7630: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
7640: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
7650: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
7660: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
7670: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 if the [sqlite3
7680: 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 ] object is.** s
7690: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 uccessfully dest
76a0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 royed and all as
76b0: 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 63 sociated resourc
76c0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 es are deallocat
76d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ed..**.** Applic
76e0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c ations must [sql
76f0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
7700: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 finalize] all [p
7710: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
7720: 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ts].** and [sqli
7730: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
7740: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
7750: 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 B handles] assoc
7760: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 iated with.** th
7770: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
7780: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 ct prior to atte
7790: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 mpting to close
77a0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 the object. ^If
77b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 .** sqlite3_clos
77c0: 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e e() is called on
77d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
77e0: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 nection] that st
77f0: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 ill has.** outst
7800: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 anding [prepared
7810: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 statements] or
7820: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
7830: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 0a then it returns.
7840: 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a ** SQLITE_BUSY..
7850: 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 **.** ^If [sqlit
7860: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 e3_close()] is i
7870: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 nvoked while a t
7880: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 ransaction is op
7890: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 en,.** the trans
78a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 action is automa
78b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 tically rolled b
78c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 ack..**.** The C
78d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
78e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
78f0: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
7900: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
7910: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 r or an [sqlite3
7920: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 ] object pointer
7930: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
7940: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
7950: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
7960: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
7970: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
7980: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 ], and not previ
7990: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a ously closed..**
79a0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
79b0: 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20 61 3_close() with a
79c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 NULL pointer ar
79d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 gument is a .**
79e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
79f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
7a00: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 t sqlite3_close(
7a10: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a sqlite3 *);../*.
7a20: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
7a30: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
7a40: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
7a50: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
7a60: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
7a70: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
7a80: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
7a90: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
7aa0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
7ab0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
7ac0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
7ad0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
7ae0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
7af0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
7b00: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
7b10: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
7b20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
7b30: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
7b40: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
7b50: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 nce wrapper arou
7b60: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 nd.** [sqlite3_p
7b70: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
7b80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
7b90: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
7ba0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 alize()],.** tha
7bb0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c t allows an appl
7bc0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d ication to run m
7bd0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e ultiple statemen
7be0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 ts of SQL.** wit
7bf0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 hout having to u
7c00: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f se a lot of C co
7c10: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de. .**.** ^The
7c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
7c30: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 nterface runs ze
7c40: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 ro or more UTF-8
7c50: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d encoded,.** sem
7c60: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 icolon-separate
7c70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
7c80: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 assed into its 2
7c90: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 nd argument,.**
7ca0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
7cb0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 connection] pass
7cd0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 ed in as its 1st
7ce0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e .** argument. ^
7cf0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
7d00: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 function of the
7d10: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 3rd argument to.
7d20: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
7d30: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 ) is not NULL, t
7d40: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
7d50: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c d for each resul
7d60: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 t row.** coming
7d70: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 out of the evalu
7d80: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
7d90: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 nts. ^The 4th a
7da0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
7db0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
7dc0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
7dd0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
7de0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
7df0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
7e00: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
7e10: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
7e20: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
7e30: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
7e40: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
7e50: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
7e60: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
7e70: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
7e80: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
7e90: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
7ea0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
7eb0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
7ec0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
7ed0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
7ee0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
7ef0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
7f00: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
7f10: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
7f20: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
7f30: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
7f40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
7f50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
7f60: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
7f70: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
7f80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
7f90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
7fa0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
7fb0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
7fc0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
7fd0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
7fe0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
7ff0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
8000: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
8010: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
8020: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
8030: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
8040: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
8050: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
8060: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
8070: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f f.** of sqlite3_
8080: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
8090: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
80a0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
80b0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
80c0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
80d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
80e0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
80f0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
8100: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
8110: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
8120: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
8130: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
8140: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
8150: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
8160: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
8170: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
8180: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
8190: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
81a0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
81b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
81c0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
81d0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
81e0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
81f0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
8200: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
8210: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
8220: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
8230: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
8240: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
8250: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
8260: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
8270: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
8280: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
8290: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
82a0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
82b0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
82c0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
82d0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
82e0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
82f0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
8300: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
8310: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
8320: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
8330: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
8340: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
8350: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
8360: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
8370: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
8380: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
8390: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
83a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
83b0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
83c0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
83d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
83e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
83f0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
8400: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
8410: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
8420: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
8430: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
8440: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
8450: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
8460: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
8470: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
8480: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
8490: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
84a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
84b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
84c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
84d0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
84e0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
84f0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
8500: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
8510: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
8520: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
8530: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
8540: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
8550: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
8560: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
8570: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
8580: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
8590: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
85a0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 ation must insur
85b0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
85c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
85d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
85e0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
85f0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
8600: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
8610: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
8620: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
8630: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 lose [database c
8640: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
8650: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 fied by.**
8660: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
8670: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
8680: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 c() while sqlite
8690: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 3_exec() is runn
86a0: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 ing..** <li> The
86b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
86c0: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 t not modify the
86d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
86e0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a ext passed into.
86f0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 ** the 2nd
8700: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c parameter of sql
8710: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c ite3_exec() whil
8720: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
8730: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
8740: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ul>.*/.SQLITE_
8750: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
8760: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
8770: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
8780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8790: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
87a0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
87b0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
87c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
87d0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
87e0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
87f0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 . int (*callbac
8800: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
8810: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a r**,char**), /*
8820: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 Callback functi
8830: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 on */. void *,
8840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8860: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 /* 1st argume
8870: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a nt to callback *
8880: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 /. char **errms
8890: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 g
88a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
88b0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 * Error msg writ
88c0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a ten here */.);..
88d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
88e0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
88f0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
8900: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d _OK {error code}
8910: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a {error codes}.*
8920: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 * KEYWORDS: {res
8930: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c ult code} {resul
8940: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d t codes}.**.** M
8950: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 any SQLite funct
8960: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 ions return an i
8970: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f nteger result co
8980: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 de from the set
8990: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e shown.** here in
89a0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 order to indica
89b0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 te success or fa
89c0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 ilure..**.** New
89d0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 error codes may
89e0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
89f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
8a00: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 SQLite..**.** Se
8a10: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f e also: [SQLITE_
8a20: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 IOERR_READ | ext
8a30: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
8a40: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 es],.** [sqlite3
8a50: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 _vtab_on_conflic
8a60: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c t()] [SQLITE_ROL
8a70: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 LBACK | result c
8a80: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e odes]..*/.#defin
8a90: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
8aa0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
8ab0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
8ac0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
8ad0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
8ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8af0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
8b00: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
8b10: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
8b20: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
8b30: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
8b40: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
8b50: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
8b60: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
8b70: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
8b80: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
8b90: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
8ba0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
8bb0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
8bc0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
8bd0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
8be0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
8bf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
8c00: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
8c10: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
8c20: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
8c30: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
8c40: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
8c50: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
8c60: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
8c70: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
8c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
8c90: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
8ca0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
8cb0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
8cc0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
8cd0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
8ce0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
8cf0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
8d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8d10: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
8d20: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
8d30: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
8d40: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
8d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8d60: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
8d70: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
8d80: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
8d90: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
8db0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
8dd0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
8de0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
8df0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
8e00: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 12 /* Unknow
8e10: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 n opcode in sqli
8e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8e30: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
8e40: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
8e50: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
8e60: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
8e70: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
8e80: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
8e90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
8ea0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
8eb0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
8ec0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
8ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
8ee0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
8ef0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
8f00: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
8f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
8f20: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
8f30: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
8f40: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
8f50: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
8f60: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
8f70: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
8f80: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
8f90: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
8fa0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
8fb0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
8fc0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
8fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
8fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
8ff0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
9000: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
9010: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
9020: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
9030: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
9040: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
9060: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
9070: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
9080: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
9090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
90a0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
90b0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
90c0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
90d0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
90e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
90f0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
9100: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
9110: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
9120: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
9130: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
9140: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
9150: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
9160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
9170: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
9180: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
9190: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
91a0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
91c0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
91d0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
91e0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
91f0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
9200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
9210: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
9220: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
9230: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
9240: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
9250: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
9260: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
9270: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
9280: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
9290: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
92a0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
92b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
92c0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
92d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
92e0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 S: {extended err
92f0: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 or code} {extend
9300: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a ed error codes}.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 ** KEYWORDS: {ex
9320: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
9330: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 de} {extended re
9340: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a sult codes}.**.*
9350: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 * In its default
9360: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
9370: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
9380: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
9390: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 f 26 integer.**
93a0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 [SQLITE_OK | res
93b0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
93c0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
93d0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
93e0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
93f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
9400: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
9410: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
9420: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
9430: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
9440: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
9450: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
9460: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
9470: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
9480: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
9490: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
94a0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
94b0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 3.3.8 and later)
94c0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 include.** supp
94d0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ort for addition
94e0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 al result codes
94f0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 that provide mor
9500: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 e detailed infor
9510: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
9520: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 errors. The exte
9530: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
9540: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 s are enabled or
9550: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 disabled.** on
9560: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 a per database c
9570: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 onnection basis
9580: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
9590: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
95a0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
95b0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f PI..**.** Some o
95c0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 f the available
95d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
95e0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 codes are listed
95f0: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 here..** One ma
9600: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d y expect the num
9610: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 ber of extended
9620: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c result codes wil
9630: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f l be expand.** o
9640: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 ver time. Softw
9650: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 are that uses ex
9660: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
9670: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 des should expec
9680: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 t.** to see new
9690: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 result codes in
96a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
96b0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
96c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 The SQLITE_OK r
96d0: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 esult code will
96e0: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 never be extende
96f0: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 d. It will alwa
9700: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 ys.** be exactly
9710: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e zero..*/.#defin
9720: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
9730: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
9740: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
9750: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
9760: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
9770: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 ORT_READ
9780: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
9790: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
97a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 SQLITE_IOERR_WRI
97b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 TE (
97c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
97d0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
97e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e QLITE_IOERR_FSYN
97f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 C (S
9800: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 QLITE_IOERR | (4
9810: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
9820: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 LITE_IOERR_DIR_F
9830: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 SYNC (SQ
9840: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c LITE_IOERR | (5<
9850: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
9860: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 ITE_IOERR_TRUNCA
9870: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c TE (SQL
9880: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c ITE_IOERR | (6<<
9890: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
98a0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 TE_IOERR_FSTAT
98b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
98c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 TE_IOERR | (7<<8
98d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
98e0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 E_IOERR_UNLOCK
98f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
9900: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 E_IOERR | (8<<8)
9910: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
9920: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 _IOERR_RDLOCK
9930: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
9940: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 _IOERR | (9<<8))
9950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9960: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 IOERR_DELETE
9970: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9980: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 IOERR | (10<<8))
9990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
99a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 IOERR_BLOCKED
99b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
99c0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 IOERR | (11<<8))
99d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
99e0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 IOERR_NOMEM
99f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9a00: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 IOERR | (12<<8))
9a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9a20: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 IOERR_ACCESS
9a30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9a40: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 IOERR | (13<<8))
9a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9a60: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 IOERR_CHECKRESER
9a70: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f VEDLOCK (SQLITE_
9a80: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 IOERR | (14<<8))
9a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9aa0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 IOERR_LOCK
9ab0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9ac0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 IOERR | (15<<8))
9ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9ae0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 IOERR_CLOSE
9af0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9b00: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 IOERR | (16<<8))
9b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9b20: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 IOERR_DIR_CLOSE
9b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9b40: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 IOERR | (17<<8))
9b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9b60: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 IOERR_SHMOPEN
9b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9b80: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 IOERR | (18<<8))
9b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9ba0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 IOERR_SHMSIZE
9bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9bc0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 IOERR | (19<<8))
9bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9be0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 IOERR_SHMLOCK
9bf0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9c00: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 IOERR | (20<<8))
9c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9c20: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 IOERR_SHMMAP
9c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9c40: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 IOERR | (21<<8))
9c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9c60: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 IOERR_SEEK
9c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
9c80: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 IOERR | (22<<8))
9c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9ca0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
9cb0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f HE (SQLITE_
9cc0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 LOCKED | (1<<8)
9cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
9ce0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 _BUSY_RECOVERY
9cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
9d00: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 _BUSY | (1<<8
9d10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
9d20: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d E_CANTOPEN_NOTEM
9d30: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 PDIR (SQLIT
9d40: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c E_CANTOPEN | (1<
9d50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
9d60: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 ITE_CANTOPEN_ISD
9d70: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c IR (SQL
9d80: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
9d90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
9da0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
9db0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
9dc0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
9dd0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
9de0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
9df0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
9e00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
9e10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
9e20: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
9e30: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
9e40: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
9e50: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
9e60: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 ine SQLITE_ABORT
9e70: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 _ROLLBACK
9e80: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 (SQLITE_ABORT
9e90: 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a | (2<<8))../*.*
9ea0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
9eb0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 s For File Open
9ec0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Operations.**.**
9ed0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 These bit value
9ee0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
9ef0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a or use in the.**
9f00: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
9f10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f o the [sqlite3_o
9f20: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
9f30: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 ace and.** in th
9f40: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
9f50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
9f60: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
9f70: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d..*/.#define SQ
9f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
9f90: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 LY 0x000
9fa0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 00001 /* Ok for
9fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
9fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
9fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
9fe0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 ITE 0x000
9ff0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 00002 /* Ok for
a000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a020: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
a030: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
a040: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 00004 /* Ok for
a050: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a060: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a070: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
a080: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 ONCLOSE 0x000
a090: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 00008 /* VFS on
a0a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a0b0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
a0c0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 IVE 0x000
a0d0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00010 /* VFS on
a0e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a0f0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 LITE_OPEN_AUTOPR
a100: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 OXY 0x000
a110: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00020 /* VFS on
a120: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a130: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 LITE_OPEN_URI
a140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
a150: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 00040 /* Ok for
a160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
a190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
a1a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00100 /* VFS on
a1b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a1c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
a1d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 B 0x000
a1e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00200 /* VFS on
a1f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
a210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 ENT_DB 0x000
a220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00400 /* VFS on
a230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
a250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
a260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 00800 /* VFS on
a270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
a290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 OURNAL 0x000
a2a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 01000 /* VFS on
a2b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a2c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
a2d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 RNAL 0x000
a2e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 02000 /* VFS on
a2f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
a310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 _JOURNAL 0x000
a320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 04000 /* VFS on
a330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ly */.#define SQ
a340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
a350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 X 0x000
a360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 08000 /* Ok for
a370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
a3a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 TEX 0x000
a3b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 10000 /* Ok for
a3c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a3d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a3e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
a3f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 CACHE 0x000
a400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20000 /* Ok for
a410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
a440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 ECACHE 0x000
a450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 40000 /* Ok for
a460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
a470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
a480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 LITE_OPEN_WAL
a490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
a4a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 80000 /* VFS on
a4b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 ly */../* Reserv
a4c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 ed:
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
a4e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a F00000 */../*.**
a4f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 CAPI3REF: Devic
a500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 e Characteristic
a510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 s.**.** The xDev
a520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
a530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 cs method of the
a540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
a550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 hods].** object
a560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
a570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 er which is a ve
a580: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 ctor of the thes
a590: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 e.** bit values
a5a0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 expressing I/O c
a5b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f haracteristics o
a5c0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 f the mass stora
a5d0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 ge.** device tha
a5e0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 t holds the file
a5f0: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 that the [sqlit
a600: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
a610: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a * refers to..**.
a620: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
a630: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
a640: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
a650: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
a660: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
a670: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
a680: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
a690: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
a6a0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
a6b0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
a6c0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
a6d0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
a6e0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
a6f0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
a700: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
a710: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
a720: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
a730: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
a740: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
a750: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
a760: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
a770: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
a780: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
a790: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
a7a0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
a7b0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
a7c0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
a7d0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
a7e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
a7f0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
a800: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
a810: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
a820: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
a830: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
a840: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
a850: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 xWrite(). The S
a860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
a870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
a880: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
a890: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 hat.** after reb
a8a0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 oot following a
a8b0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c crash or power l
a8c0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 oss, the only by
a8d0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 tes in a.** file
a8e0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 that were writt
a8f0: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 en at the applic
a900: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 ation level migh
a910: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a t have changed.*
a920: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 * and that adjac
a930: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 ent bytes, even
a940: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 bytes within the
a950: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 same sector are
a960: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 .** guaranteed t
a970: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a o be unchanged..
a980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
a990: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
a9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
a9b0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
a9c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
a9d0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
a9e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
a9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
aa00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
aa20: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
aa30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
aa40: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
aa50: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
aa60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
aa70: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
aa80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
aa90: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
aaa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
aab0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
aac0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
aad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
aae0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
aaf0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
ab00: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
ab10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
ab20: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
ab30: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
ab40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
ab50: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
ab60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
ab70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
ab80: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
ab90: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
aba0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
abb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
abc0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
abd0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
abe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
abf0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
ac00: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
ac10: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
ac20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
ac30: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
ac40: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 0x00001000../
ac50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
ac60: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
ac70: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
ac80: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
ac90: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
aca0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
acb0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
acc0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
acd0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
ace0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
acf0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
ad00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
ad10: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
ad20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
ad30: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
ad40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
ad50: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
ad60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
ad70: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
ad80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
ad90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
ada0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
adb0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
adc0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
add0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
ade0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
adf0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
ae00: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
ae10: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
ae20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
ae30: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
ae40: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
ae50: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
ae60: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
ae70: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
ae80: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
ae90: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
aea0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
aeb0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
aec0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
aed0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
aee0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
aef0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
af00: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
af10: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
af20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
af30: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
af40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
af50: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
af60: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
af70: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
af80: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
af90: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
afa0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
afb0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
afc0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
afd0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
afe0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
aff0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
b000: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
b010: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
b020: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
b030: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
b040: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
b050: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
b060: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
b070: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
b080: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
b090: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
b0a0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
b0b0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
b0c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
b0d0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
b0e0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
b0f0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
b100: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
b110: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
b120: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
b130: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
b140: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
b150: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
b160: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
b170: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
b180: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
b190: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
b1a0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
b1b0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
b1c0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
b1d0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
b1e0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
b1f0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
b200: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
b210: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
b220: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
b230: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
b240: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
b250: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
b260: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
b270: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
b280: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
b290: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
b2a0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
b2b0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
b2c0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
b2d0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
b2e0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
b2f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
b300: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
b310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
b320: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
b330: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
b340: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
b350: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
b360: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
b370: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
b380: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
b390: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
b3a0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
b3b0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
b3c0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
b3d0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
b3e0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
b3f0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
b400: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
b410: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
b420: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
b430: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
b440: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
b450: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
b460: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
b470: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
b480: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
b490: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
b4a0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
b4b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
b4c0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
b4d0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
b4e0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
b4f0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
b500: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
b510: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
b520: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
b530: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
b540: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
b550: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
b560: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
b570: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
b580: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
b590: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
b5a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
b5b0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
b5c0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
b5d0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
b5e0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
b5f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
b600: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
b610: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
b620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
b630: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
b640: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
b650: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
b660: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
b670: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
b680: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
b690: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
b6a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
b6b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
b6c0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
b6d0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
b6e0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
b6f0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
b700: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
b710: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
b720: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
b730: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
b740: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
b750: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
b760: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
b770: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
b780: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
b790: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
b7a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
b7b0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
b7c0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
b7d0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
b7e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
b7f0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
b800: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
b810: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
b820: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
b830: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
b840: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
b850: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
b860: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
b870: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
b880: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
b890: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
b8a0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
b8b0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
b8c0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
b8d0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
b8e0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
b8f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
b900: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
b910: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
b920: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
b930: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
b940: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
b950: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
b960: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
b970: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
b980: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
b990: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
b9a0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
b9b0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
b9c0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
b9d0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
b9e0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
b9f0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
ba00: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
ba10: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
ba20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
ba30: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
ba40: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
ba50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
ba60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
ba70: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
ba80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
ba90: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
baa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
bab0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
bac0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
bad0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
bae0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
baf0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
bb00: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
bb10: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
bb20: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
bb30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
bb40: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
bb50: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
bb60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
bb70: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
bb80: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
bb90: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
bba0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
bbb0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
bbc0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
bbd0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
bbe0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
bbf0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
bc00: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
bc10: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
bc20: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
bc30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
bc40: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
bc50: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
bc60: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
bc70: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
bc80: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
bc90: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
bca0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
bcb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
bcc0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
bcd0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
bce0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
bcf0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
bd00: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
bd10: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
bd20: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
bd30: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
bd40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
bd50: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
bd60: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
bd70: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
bd80: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
bd90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
bda0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
bdb0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
bdc0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
bdd0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
bde0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
bdf0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
be00: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
be10: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
be20: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
be30: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
be40: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
be50: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
be60: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
be70: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
be80: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
be90: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
bea0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
beb0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
bec0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
bed0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f e..** A [SQLITE_
bee0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
bef0: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 | list of opcode
bf00: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 s] less than 100
bf10: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a is available..*
bf20: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
bf30: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 hat define a cus
bf40: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c tom xFileControl
bf50: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 method should u
bf60: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 se opcodes.** gr
bf70: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 eater than 100 t
bf80: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 o avoid conflict
bf90: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e s. VFS implemen
bfa0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a tations should.*
bfb0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
bfc0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 _NOTFOUND] for f
bfd0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
bfe0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f des that they do
bff0: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a not.** recogniz
c000: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 e..**.** The xSe
c010: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f ctorSize() metho
c020: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 d returns the se
c030: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 ctor size of the
c040: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
c050: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 underlies the fi
c060: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 le. The sector
c070: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d size is the.** m
c080: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 inimum write tha
c090: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d t can be perform
c0a0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 ed without distu
c0b0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 rbing.** other b
c0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
c0d0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 . The xDeviceCh
c0e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a aracteristics().
c0f0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
c100: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 s a bit vector d
c110: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 escribing behavi
c120: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e ors of the.** un
c130: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a derlying device:
c140: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
c150: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
c160: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 P_ATOMIC].** <li
c170: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
c180: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c ATOMIC512].** <l
c190: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c1a0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC1K].** <l
c1b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c1c0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC2K].** <l
c1d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c1e0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC4K].** <l
c1f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c200: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c _ATOMIC8K].** <l
c210: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
c220: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c _ATOMIC16K].** <
c230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
c240: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 P_ATOMIC32K].**
c250: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
c260: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a AP_ATOMIC64K].**
c270: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
c280: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d CAP_SAFE_APPEND]
c290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c2a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
c2b0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a L].** </ul>.**.*
c2c0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 * The SQLITE_IOC
c2d0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 AP_ATOMIC proper
c2e0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c ty means that al
c2f0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 l writes of.** a
c300: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d ny size are atom
c310: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
c320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 IOCAP_ATOMICnnn
c330: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 values.** mean t
c340: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c hat writes of bl
c350: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e ocks that are nn
c360: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 n bytes in size
c370: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e and.** are align
c380: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 ed to an address
c390: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 which is an int
c3a0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 eger multiple of
c3b0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d .** nnn are atom
c3c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
c3d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
c3e0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a D value means.**
c3f0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 that when data
c400: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 is appended to a
c410: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 file, the data
c420: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 is appended.** f
c430: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 irst then the si
c440: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 ze of the file i
c450: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 s extended, neve
c460: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 r the other.** w
c470: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 ay around. The
c480: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
c490: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 UENTIAL property
c4a0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 means that.** i
c4b0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 nformation is wr
c4c0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e itten to disk in
c4d0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 the same order
c4e0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 as calls.** to x
c4f0: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 Write()..**.** I
c500: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e f xRead() return
c510: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 s SQLITE_IOERR_S
c520: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 HORT_READ it mus
c530: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 t also fill.** i
c540: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 n the unread por
c550: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 tions of the buf
c560: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 fer with zeros.
c570: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 A VFS that.** f
c580: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c ails to zero-fil
c590: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 l short reads mi
c5a0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b ght seem to work
c5b0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
c5c0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 ailure to zero-f
c5d0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 ill short reads
c5e0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 will eventually
c5f0: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 lead to.** datab
c600: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a ase corruption..
c610: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
c620: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
c630: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f hods sqlite3_io_
c640: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
c650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
c660: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 ds {. int iVers
c670: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c ion;. int (*xCl
c680: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ose)(sqlite3_fil
c690: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 e*);. int (*xRe
c6a0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ad)(sqlite3_file
c6b0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 *, void*, int iA
c6c0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
c6d0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
c6e0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 (*xWrite)(sqlite
c6f0: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 3_file*, const v
c700: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
c710: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
c720: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 fst);. int (*xT
c730: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 runcate)(sqlite3
c740: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
c750: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 int64 size);. i
c760: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
c770: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 te3_file*, int f
c780: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
c790: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 FileSize)(sqlite
c7a0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
c7b0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a _int64 *pSize);.
c7c0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 int (*xLock)(s
c7d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
c7e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c t);. int (*xUnl
c7f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
c800: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
c810: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 (*xCheckReserved
c820: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
c830: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 le*, int *pResOu
c840: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c t);. int (*xFil
c850: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 eControl)(sqlite
c860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 3_file*, int op,
c870: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 void *pArg);.
c880: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
c890: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
c8a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
c8b0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
c8c0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
c8d0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 );. /* Methods
c8e0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 above are valid
c8f0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f for version 1 */
c900: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 . int (*xShmMap
c910: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
c920: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 int iPg, int pg
c930: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f sz, int, void vo
c940: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 latile**);. int
c950: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c (*xShmLock)(sql
c960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
c970: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 offset, int n, i
c980: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 nt flags);. voi
c990: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 d (*xShmBarrier)
c9a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
c9b0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d . int (*xShmUnm
c9c0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ap)(sqlite3_file
c9d0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 *, int deleteFla
c9e0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 g);. /* Methods
c9f0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 above are valid
ca00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a for version 2 *
ca10: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 /. /* Additiona
ca20: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 l methods may be
ca30: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
ca40: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a releases */.};.
ca50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ca60: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 Standard File C
ca70: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a ontrol Opcodes.*
ca80: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
ca90: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
caa0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
cab0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
cac0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
cad0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
cae0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
caf0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
cb00: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
cb10: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
cb20: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
cb30: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
cb40: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
cb50: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
cb60: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
cb70: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
cb80: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
cb90: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 write the curre
cba0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 nt state of.** t
cbb0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 he lock (one of
cbc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
cbd0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b E], [SQLITE_LOCK
cbe0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 _SHARED],.** [SQ
cbf0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
cc00: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ED], [SQLITE_LOC
cc10: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b K_PENDING], or [
cc20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
cc30: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 USIVE]).** into
cc40: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 an integer that
cc50: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
cc60: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 t points to. Thi
cc70: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 s capability.**
cc80: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 is used during t
cc90: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 esting and only
cca0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 needs to be supp
ccb0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 orted when SQLIT
ccc0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 E_TEST.** is def
ccd0: 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ined..** <ul>.**
cce0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
ccf0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a NTL_SIZE_HINT]].
cd00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
cd10: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 CNTL_SIZE_HINT]
cd20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 opcode is used b
cd30: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 y SQLite to give
cd40: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 the VFS.** laye
cd50: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 r a hint of how
cd60: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 large the databa
cd70: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f se file will gro
cd80: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 w to be during t
cd90: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 he.** current tr
cda0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 ansaction. This
cdb0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 hint is not gua
cdc0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 ranteed to be ac
cdd0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a curate but it.**
cde0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e is often close.
cdf0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 The underlying
ce00: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 VFS might choos
ce10: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 e to preallocate
ce20: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
ce30: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e e space based on
ce40: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 this hint in or
ce50: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 der to help writ
ce60: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 es to the databa
ce70: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 se.** file run f
ce80: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 aster..**.** <li
ce90: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
cea0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 CHUNK_SIZE]].**
ceb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
cec0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 L_CHUNK_SIZE] op
ced0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
cee0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 request that the
cef0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 VFS.** extends
cf00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 and truncates th
cf10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
cf20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 in chunks of a s
cf30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a ize specified.**
cf40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 by the user. Th
cf50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
cf60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 t to [sqlite3_fi
cf70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 le_control()] sh
cf80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 ould .** point t
cf90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 o an integer (ty
cfa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 pe int) containi
cfb0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b ng the new chunk
cfc0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 -size to use.**
cfd0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 for the nominate
cfe0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f d database. Allo
cff0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 cating database
d000: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 file space in la
d010: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 rge.** chunks (s
d020: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 ay 1MB at a time
d030: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 ), may reduce fi
d040: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 le-system fragme
d050: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 ntation and.** i
d060: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e mprove performan
d070: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 ce on some syste
d080: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ms..**.** <li>[[
d090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
d0a0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 E_POINTER]].** T
d0b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
d0c0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f _FILE_POINTER] o
d0d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
d0e0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 obtain a pointe
d0f0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c r.** to the [sql
d100: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
d110: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 t associated wit
d120: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
d130: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
d140: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 ction. See the
d150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
d160: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e ntrol()] documen
d170: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 tation for.** ad
d180: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
d190: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e tion..**.** <li>
d1a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [[SQLITE_FCNTL_S
d1b0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a YNC_OMITTED]].**
d1c0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ^(The [SQLITE_F
d1d0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
d1e0: 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e D] opcode is gen
d1f0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c erated internall
d200: 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 y by.** SQLite a
d210: 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 nd sent to all V
d220: 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 FSes in place of
d230: 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 a call to the x
d240: 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 Sync method.** w
d250: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
d260: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 connection has
d270: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
d280: 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e ous] set to OFF.
d290: 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 )^.** Some speci
d2a0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 alized VFSes nee
d2b0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e d this signal in
d2c0: 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 order to operat
d2d0: 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 e correctly.** w
d2e0: 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 hen [PRAGMA sync
d2f0: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 hronous | PRAGMA
d300: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 synchronous=OFF
d310: 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f ] is set, but mo
d320: 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 st .** VFSes do
d330: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
d340: 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 gnal and should
d350: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 silently ignore
d360: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 this opcode..**
d370: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
d380: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 uld not call [sq
d390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
d3a0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a ol()] with this.
d3b0: 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 ** opcode as doi
d3c0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 ng so may disrup
d3d0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 t the operation
d3e0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
d3f0: 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 ed VFSes.** that
d400: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 do require it.
d410: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 .**.** <li>[[SQ
d420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
d430: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e _AV_RETRY]].** ^
d440: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d450: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 L_WIN32_AV_RETRY
d460: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
d470: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 to configure au
d480: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 tomatic.** retry
d490: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 counts and inte
d4a0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 rvals for certai
d4b0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 n disk I/O opera
d4c0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a tions for the.**
d4d0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 windows [VFS] i
d4e0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 n order to provi
d4f0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e de robustness in
d500: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 the presence of
d510: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 .** anti-virus p
d520: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 rograms. By def
d530: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 ault, the window
d540: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 s VFS will retry
d550: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 file read,.** f
d560: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 ile write, and f
d570: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 ile delete opera
d580: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 tions up to 10 t
d590: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c imes, with a del
d5a0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c ay.** of 25 mill
d5b0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 iseconds before
d5c0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 the first retry
d5d0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c and with the del
d5e0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a ay increasing.**
d5f0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 by an additiona
d600: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 l 25 millisecond
d610: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 s with each subs
d620: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 equent retry. T
d630: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c his.** opcode al
d640: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 lows these two v
d650: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 alues (10 retrie
d660: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 s and 25 millise
d670: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a conds of delay).
d680: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 ** to be adjuste
d690: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 d. The values a
d6a0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 re changed for a
d6b0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ll database conn
d6c0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 ections.** withi
d6d0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 n the same proce
d6e0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e ss. The argumen
d6f0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
d700: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 o an array of tw
d710: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 o.** integers wh
d720: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e ere the first in
d730: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 teger i the new
d740: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 retry count and
d750: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e the second.** in
d760: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c teger is the del
d770: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 ay. If either i
d780: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 nteger is negati
d790: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 ve, then the set
d7a0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 ting.** is not c
d7b0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 hanged but inste
d7c0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ad the prior val
d7d0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 ue of that setti
d7e0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a ng is written.**
d7f0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 into the array
d800: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 entry, allowing
d810: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 the current retr
d820: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 y settings to be
d830: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 .** interrogated
d840: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 . The zDbName p
d850: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f arameter is igno
d860: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b red..**.** <li>[
d870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
d880: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e RSIST_WAL]].** ^
d890: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d8a0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f L_PERSIST_WAL] o
d8b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
d8c0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 set or query th
d8d0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 e.** persistent
d8e0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48 65 [WAL | Write AHe
d8f0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e ad Log] setting.
d900: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 By default, th
d910: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 e auxiliary.** w
d920: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 rite ahead log a
d930: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
d940: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 files used for
d950: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 transaction cont
d960: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d rol.** are autom
d970: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
d980: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 when the latest
d990: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 connection to t
d9a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
d9b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 loses. Setting
d9c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
d9d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 ode causes those
d9e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 files to persis
d9f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 t after.** close
da00: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 . Persisting th
da10: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 e files is usefu
da20: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f l when other pro
da30: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e cesses that do n
da40: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 ot.** have write
da50: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 permission on t
da60: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e he directory con
da70: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 taining the data
da80: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a base file want.*
da90: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 * to read the da
daa0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 tabase file, as
dab0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 the WAL and shar
dac0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 ed memory files
dad0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e must exist.** in
dae0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 order for the d
daf0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
db00: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 adable. The fou
db10: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
db20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
db30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
db40: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
db50: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
db60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
db70: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
db80: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
db90: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
dba0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
dbb0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a le persistent.**
dbc0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 WAL mode. If t
dbd0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
dbe0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
dbf0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
dc00: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c e current.** WAL
dc10: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 persistence set
dc20: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ting..**.** <li>
dc30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
dc40: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
dc50: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 TE]].** ^The [SQ
dc60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
dc70: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 SAFE_OVERWRITE]
dc80: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
dc90: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
dca0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
dcb0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 "powersafe-over
dcc0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 write" or "PSOW"
dcd0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 setting. The P
dce0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 SOW setting.** d
dcf0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 etermines the [S
dd00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
dd10: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
dd20: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 bit of the.** x
dd30: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
dd40: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 stics methods. T
dd50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
dd60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
dd70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
dd80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
dd90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
dda0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
ddb0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
ddc0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
ddd0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 sable zero-damag
dde0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 e mode or 1 to e
ddf0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 nable zero-damag
de00: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 e.** mode. If t
de10: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
de20: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
de30: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
de40: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 e current.** zer
de50: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 o-damage mode se
de60: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
de70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
de80: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e OVERWRITE]].** ^
de90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
dea0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 L_OVERWRITE] opc
deb0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 ode is invoked b
dec0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f y SQLite after o
ded0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 pening.** a writ
dee0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f e transaction to
def0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 indicate that,
df00: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c unless it is rol
df10: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d led back for som
df20: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 e.** reason, the
df30: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 entire database
df40: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 file will be ov
df50: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 erwritten by the
df60: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 current .** tra
df70: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 nsaction. This i
df80: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d s used by VACUUM
df90: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
dfa0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
dfb0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a FCNTL_VFSNAME]].
dfc0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
dfd0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f FCNTL_VFSNAME] o
dfe0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 pcode can be use
dff0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
e000: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 names of.** all
e010: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 [VFSes] in the V
e020: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e FS stack. The n
e030: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 ames are of all
e040: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 VFS shims and th
e050: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f e.** final botto
e060: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 m-level VFS are
e070: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
e080: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
e090: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d m .** [sqlite3_m
e0a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 alloc()] and the
e0b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 result is store
e0c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 d in the char* v
e0d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 ariable.** that
e0e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
e0f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 eter of [sqlite3
e100: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
e110: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 points to..** T
e120: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 he caller is res
e130: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 ponsible for fre
e140: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 eing the memory
e150: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 when done. As w
e160: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d ith.** all file-
e170: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c control actions,
e180: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 there is no gua
e190: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 rantee that this
e1a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a will actually.*
e1b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 * do anything.
e1c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 Callers should i
e1d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 nitialize the ch
e1e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 ar* variable to
e1f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
e200: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 r in case this f
e210: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e ile-control is n
e220: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 ot implemented.
e230: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 This file-contr
e240: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 ol.** is intende
e250: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 d for diagnostic
e260: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a use only..**.**
e270: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e280: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 NTL_PRAGMA]].**
e290: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 ^Whenever a [PRA
e2a0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 GMA] statement i
e2b0: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 s parsed, an [SQ
e2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
e2d0: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 A] .** file cont
e2e0: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 rol is sent to t
e2f0: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 he open [sqlite3
e300: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f _file] object co
e310: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 rresponding.** t
e320: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
e330: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 ile to which the
e340: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e pragma statemen
e350: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 t refers. ^The a
e360: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 rgument.** to th
e370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
e380: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e PRAGMA] file con
e390: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 trol is an array
e3a0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 of.** pointers
e3b0: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 to strings (char
e3c0: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 **) in which the
e3d0: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 second element
e3e0: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 of the array.**
e3f0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
e400: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 he pragma and th
e410: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 e third element
e420: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 is the argument
e430: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 to the.** pragma
e440: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 or NULL if the
e450: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 pragma has no ar
e460: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 gument. ^The ha
e470: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 ndler for an.**
e480: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
e490: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
e4a0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c ol can optionall
e4b0: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 y make the first
e4c0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 element.** of t
e4d0: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 he char** argume
e4e0: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 nt point to a st
e4f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 ring obtained fr
e500: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 om [sqlite3_mpri
e510: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 ntf()].** or the
e520: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 equivalent and
e530: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c that string will
e540: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 become the resu
e550: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 lt of the pragma
e560: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 or.** the error
e570: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 message if the
e580: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 pragma fails. ^I
e590: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
e5a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
e5b0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
e5c0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 rns [SQLITE_NOTF
e5d0: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d OUND], then norm
e5e0: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 al .** [PRAGMA]
e5f0: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 processing conti
e600: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b nues. ^If the [
e610: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
e620: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e GMA].** file con
e630: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 trol returns [SQ
e640: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 LITE_OK], then t
e650: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 he parser assume
e660: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 s that the.** VF
e670: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 S has handled th
e680: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 e PRAGMA itself
e690: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 and the parser g
e6a0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 enerates a no-op
e6b0: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
e6c0: 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 tement. ^If the
e6d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
e6e0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
e6f0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 rol returns.** a
e700: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f ny result code o
e710: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
e720: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 E_OK] or [SQLITE
e730: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 _NOTFOUND], that
e740: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 means.** that t
e750: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 he VFS encounter
e760: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c ed an error whil
e770: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b e handling the [
e780: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a PRAGMA] and the.
e790: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f ** compilation o
e7a0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 f the PRAGMA fai
e7b0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ls with an error
e7c0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
e7d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a FCNTL_PRAGMA].**
e7e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 file control oc
e7f0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 curs at the begi
e800: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 nning of pragma
e810: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 statement analys
e820: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 is and so.** it
e830: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 is able to overr
e840: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 ide built-in [PR
e850: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 AGMA] statements
e860: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 ..** </ul>.*/.#d
e870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
e880: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 TL_LOCKSTATE
e890: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
e8a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f fine SQLITE_GET_
e8b0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
e8c0: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
e8d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
e8e0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
e8f0: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 3.#defi
e900: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 ne SQLITE_LAST_E
e910: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
e920: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
e930: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
e940: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 IZE_HINT
e950: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
e960: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 SQLITE_FCNTL_CH
e970: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 UNK_SIZE
e980: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
e990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
e9a0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 E_POINTER
e9b0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 7.#define S
e9c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
e9d0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 _OMITTED
e9e0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
e9f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
ea00: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 _AV_RETRY
ea10: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 9.#define SQL
ea20: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
ea30: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 T_WAL
ea40: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
ea50: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 TE_FCNTL_OVERWRI
ea60: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
ea70: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 11.#define SQLIT
ea80: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 E_FCNTL_VFSNAME
ea90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
eaa0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
eab0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
eac0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 _OVERWRITE 13
ead0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
eae0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 FCNTL_PRAGMA
eaf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 14.
eb00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
eb10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
eb20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
eb30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
eb40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
eb50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
eb60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
eb70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
eb80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
eb90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
eba0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
ebb0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
ebc0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
ebd0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
ebe0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
ebf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
ec00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
ec10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
ec20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
ec30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
ec40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
ec50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
ec60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
ec70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
ec80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
ec90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
eca0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
ecb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
ecc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
ecd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
ece0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
ecf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
ed00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
ed10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
ed20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
ed30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
ed40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
ed50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
ed60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
ed70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
ed80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
ed90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
eda0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
edb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
edc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
edd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
ede0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
edf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
ee00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
ee10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
ee20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
ee30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
ee40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
ee50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
ee60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
ee70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
ee80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
ee90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
eea0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
eeb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
eec0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
eed0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
eee0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
eef0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
ef00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
ef10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
ef20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
ef30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
ef40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
ef50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
ef60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
ef70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
ef80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
ef90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
efa0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
efb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
efc0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
efd0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
efe0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
eff0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
f000: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
f010: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
f020: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
f030: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
f040: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
f050: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
f060: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
f070: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
f080: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
f090: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
f0a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
f0b0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
f0c0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
f0d0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
f0e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
f0f0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
f100: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
f110: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
f120: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
f140: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
f150: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
f160: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
f170: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
f180: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
f190: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
f1a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
f1b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
f1c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
f1d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
f1e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
f1f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
f200: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
f210: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
f220: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
f230: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
f240: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
f250: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
f260: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
f270: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
f280: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
f290: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
f2a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
f2b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
f2c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
f2d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
f2e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
f2f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
f300: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
f310: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
f320: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
f330: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
f340: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
f350: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
f360: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
f370: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
f380: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
f390: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
f3a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
f3b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
f3c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
f3d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
f3e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
f3f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
f400: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
f410: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
f420: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
f430: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
f440: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
f450: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
f460: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
f470: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
f480: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
f490: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
f4a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
f4b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
f4c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
f4d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
f4e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
f4f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
f500: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
f510: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
f520: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
f530: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
f540: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
f550: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
f560: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
f570: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
f580: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
f590: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
f5a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
f5b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
f5c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
f5d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
f5e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
f5f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
f600: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
f610: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
f620: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
f630: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
f640: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
f650: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
f660: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
f670: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
f680: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
f690: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
f6a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
f6b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
f6c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
f6d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
f6e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
f6f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
f700: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
f710: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
f720: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
f730: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
f740: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
f750: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
f760: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
f770: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
f780: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
f790: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
f7a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
f7b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
f7c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
f7d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
f7e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
f7f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
f800: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
f810: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
f820: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
f830: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
f840: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
f850: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
f860: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
f870: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
f880: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
f890: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
f8a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
f8b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
f8c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
f8d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
f8e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
f8f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
f900: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
f910: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
f920: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
f930: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
f940: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
f950: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
f960: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
f970: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
f980: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
f990: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
f9a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
f9b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
f9c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
f9d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
f9e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
f9f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
fa00: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
fa10: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
fa20: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
fa30: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
fa40: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
fa50: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
fa60: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
fa70: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
fa80: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
fa90: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
faa0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
fab0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
fac0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
fad0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
fae0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
faf0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
fb00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
fb10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
fb20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
fb30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
fb40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
fb50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
fb60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
fb70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
fb80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
fb90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
fba0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
fbb0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
fbc0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
fbd0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
fbe0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
fbf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
fc00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
fc10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
fc20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
fc30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
fc40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
fc50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
fc60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
fc70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
fc80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
fc90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
fca0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
fcb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
fcc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
fcd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
fce0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
fcf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
fd00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
fd10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
fd20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
fd30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
fd40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
fd50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
fd60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
fd70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
fd80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
fd90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
fda0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
fdb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
fdc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
fdd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
fde0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
fdf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
fe00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
fe10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
fe20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
fe30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
fe40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
fe50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
fe60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
fe70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
fe80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
fe90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
fea0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
feb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
fec0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
fed0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
fee0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
fef0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
ff00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
ff10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
ff20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
ff30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
ff40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
ff50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
ff60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
ff70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
ff80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
ff90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
ffa0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
ffb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
ffc0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
ffd0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
ffe0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
fff0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
10000 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
10010 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
10020 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
10030 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
10040 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
10050 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
10060 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
10070 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
10080 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
10090 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
100a0 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
100b0 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
100c0 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
100d0 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
100e0 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
100f0 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
10100 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
10110 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
10120 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
10130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
10140 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
10150 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
10160 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
10170 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
10180 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
10190 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
101a0 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
101b0 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
101c0 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
101d0 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
101e0 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
101f0 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
10200 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
10210 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
10220 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
10230 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
10240 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
10250 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
10260 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
10270 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
10280 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
10290 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
102a0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
102b0 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
102c0 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
102d0 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
102e0 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
102f0 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
10300 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
10310 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
10320 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
10330 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
10340 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
10350 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
10360 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
10370 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
10380 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
10390 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
103a0 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
103b0 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
103c0 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
103d0 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
103e0 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
103f0 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
10400 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
10410 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
10420 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
10430 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
10440 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
10450 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
10460 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
10470 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
10480 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
10490 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
104a0 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
104b0 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
104c0 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
104d0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
104e0 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
104f0 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
10500 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
10510 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
10520 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
10530 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
10540 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
10550 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
10560 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
10570 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
10580 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
10590 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
105a0 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
105b0 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
105c0 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
105d0 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
105e0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
105f0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
10600 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
10610 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
10620 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
10630 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
10640 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
10650 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
10660 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10670 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
10680 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
10690 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
106a0 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
106b0 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
106c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
106d0 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
106e0 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
106f0 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
10700 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
10710 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10720 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
10730 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
10740 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
10750 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
10760 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
10770 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
10780 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
10790 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
107a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
107b0 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
107c0 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
107d0 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
107e0 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
107f0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
10800 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
10810 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
10820 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
10830 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
10840 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
10850 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
10860 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
10870 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
10880 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
10890 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
108a0 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
108b0 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
108c0 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
108d0 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
108e0 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
108f0 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
10900 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
10910 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
10920 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
10930 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
10940 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
10950 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
10960 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
10970 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
10980 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
10990 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
109a0 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
109b0 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
109c0 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
109d0 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
109e0 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
109f0 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
10a00 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
10a10 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
10a20 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
10a30 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
10a40 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
10a50 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
10a60 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
10a70 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
10a80 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
10a90 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
10aa0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
10ab0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
10ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
10ad0 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
10ae0 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
10af0 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
10b00 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
10b10 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
10b20 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
10b30 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
10b40 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
10b50 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
10b60 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
10b70 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
10b80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
10b90 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
10ba0 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
10bb0 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
10bc0 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
10bd0 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
10be0 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
10bf0 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
10c00 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
10c10 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
10c20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
10c30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
10c40 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
10c50 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
10c60 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
10c70 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
10c80 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
10c90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
10ca0 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
10cb0 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
10cc0 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
10cd0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
10ce0 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
10cf0 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
10d00 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
10d10 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
10d20 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
10d30 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
10d40 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
10d50 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
10d60 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
10d70 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
10d80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
10d90 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
10da0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
10db0 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
10dc0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
10dd0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
10de0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
10df0 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
10e00 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
10e10 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
10e20 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
10e30 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
10e40 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
10e50 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
10e60 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
10e70 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
10e80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
10e90 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
10ea0 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
10eb0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
10ec0 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
10ed0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
10ee0 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
10ef0 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
10f00 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
10f10 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
10f20 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
10f30 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
10f40 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
10f50 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
10f60 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
10f70 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
10f80 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
10f90 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
10fa0 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
10fb0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
10fc0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
10fd0 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
10fe0 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
10ff0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
11000 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
11010 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
11020 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
11030 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
11040 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
11050 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
11060 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
11070 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
11080 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
11090 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
110a0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
110b0 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
110c0 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
110d0 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
110e0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
110f0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
11100 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
11110 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
11120 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
11130 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
11140 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
11150 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
11160 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
11170 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
11180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
11190 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
111a0 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
111b0 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
111c0 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
111d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
111e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
111f0 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
11200 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
11210 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
11220 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
11230 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
11240 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
11250 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
11260 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
11270 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
11280 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
11290 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
112a0 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
112b0 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
112c0 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
112d0 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
112e0 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
112f0 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
11300 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
11310 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
11320 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
11330 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
11340 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
11350 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
11360 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
11370 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
11380 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
11390 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
113a0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
113b0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
113c0 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
113d0 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
113e0 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
113f0 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
11400 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
11410 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
11420 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
11430 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
11440 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
11450 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
11460 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
11470 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
11480 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
11490 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
114a0 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
114b0 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
114c0 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
114d0 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
114e0 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
114f0 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
11500 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
11510 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
11520 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
11530 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
11540 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
11550 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
11560 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
11570 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
11580 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
11590 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
115a0 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
115b0 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
115c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
115d0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
115e0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
115f0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
11600 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
11610 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
11620 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
11630 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
11640 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
11650 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
11660 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
11670 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
11680 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
11690 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
116a0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
116b0 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
116c0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
116d0 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
116e0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
116f0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
11700 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
11710 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
11720 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
11730 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
11740 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
11750 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
11760 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
11770 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
11780 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
11790 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
117a0 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
117b0 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
117c0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
117d0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
117e0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
117f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
11800 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
11810 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
11820 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
11830 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
11840 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
11850 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
11860 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
11870 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
11880 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
11890 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
118a0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
118b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
118c0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
118d0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
118e0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
118f0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
11900 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
11910 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
11920 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
11930 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
11940 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
11950 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
11960 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 was given no th
11970 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
11980 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
11990 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
119a0 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
119b0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
119c0 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
119d0 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
119e0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
119f0 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
11a00 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
11a10 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
11a20 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
11a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
11a40 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
11a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
11a60 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
11a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
11a80 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
11a90 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
11aa0 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
11ab0 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
11ac0 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
11ad0 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
11ae0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
11af0 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
11b00 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
11b10 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
11b20 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
11b30 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
11b40 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
11b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
11b60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
11b70 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
11b80 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
11b90 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
11ba0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
11bb0 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
11bc0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
11bd0 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
11be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
11bf0 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
11c00 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
11c10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
11c20 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
11c30 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
11c40 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
11c50 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
11c60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
11c70 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
11c80 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
11c90 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
11ca0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
11cb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
11cc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
11cd0 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
11ce0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
11cf0 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
11d00 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
11d10 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
11d20 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
11d30 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
11d40 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
11d50 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
11d60 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
11d70 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
11d80 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
11d90 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
11da0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
11db0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
11dc0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
11dd0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
11de0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11df0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
11e00 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
11e10 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
11e20 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
11e30 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
11e40 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
11e50 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
11e60 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
11e70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
11e80 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
11e90 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
11ea0 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
11eb0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
11ec0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
11ed0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
11ee0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
11ef0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
11f00 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
11f10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
11f20 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
11f30 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
11f40 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
11f50 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
11f60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
11f70 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
11f80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
11f90 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
11fa0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
11fb0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
11fc0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
11fd0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
11fe0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
11ff0 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
12000 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
12010 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
12020 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
12030 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
12040 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
12050 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
12060 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
12070 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
12080 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
12090 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
120a0 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
120b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
120c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
120d0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
120e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
120f0 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
12100 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
12110 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
12120 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
12130 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
12140 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
12150 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12160 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
12170 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
12180 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12190 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
121a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
121b0 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
121c0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
121d0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
121e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
121f0 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
12200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12210 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
12220 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
12230 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
12240 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
12250 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
12260 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
12270 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
12280 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
12290 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
122a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
122b0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
122c0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
122d0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
122e0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
122f0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
12300 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
12310 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
12320 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
12330 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
12340 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
12350 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
12360 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
12370 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
12380 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
12390 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
123a0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
123b0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
123c0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
123d0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
123e0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
123f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12400 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
12410 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
12420 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
12430 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
12440 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
12450 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
12460 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
12470 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
12480 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
12490 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
124a0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
124b0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
124c0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
124d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
124e0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
124f0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
12500 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
12510 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
12520 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
12530 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
12540 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12550 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
12560 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
12570 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
12580 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
12590 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
125a0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
125b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
125c0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
125d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
125e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
125f0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
12600 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
12610 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
12620 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
12630 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
12640 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
12650 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
12660 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
12670 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
12680 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
12690 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
126a0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
126b0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
126c0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
126d0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
126e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
126f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
12700 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
12710 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
12720 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
12730 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
12740 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
12750 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
12760 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
12770 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
12780 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
12790 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
127a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
127b0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
127c0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
127d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
127e0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
127f0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
12800 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
12810 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
12820 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
12830 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
12840 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
12850 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
12860 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
12870 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
12880 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
12890 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
128a0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
128b0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
128c0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
128d0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
128e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
128f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
12900 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
12910 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
12920 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
12930 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
12940 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
12950 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
12960 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
12970 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
12980 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
12990 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
129a0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
129b0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
129c0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
129d0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
129e0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
129f0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
12a00 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
12a10 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
12a20 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
12a30 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12a40 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
12a50 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
12a60 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
12a70 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
12a80 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
12a90 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
12aa0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
12ab0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
12ac0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
12ad0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
12ae0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
12af0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
12b00 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
12b10 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
12b20 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
12b30 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12b40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
12b50 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
12b60 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
12b70 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
12b80 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
12b90 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
12ba0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12bb0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
12bc0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
12bd0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
12be0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
12bf0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
12c00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
12c10 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
12c20 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
12c30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
12c40 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
12c50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
12c60 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
12c70 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f t(void);.SQLITE_
12c80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
12c90 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
12ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
12cb0 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
12cc0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
12cd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12ce0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
12cf0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
12d00 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
12d10 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
12d20 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
12d30 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
12d40 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
12d50 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
12d60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
12d70 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
12d80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
12d90 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
12da0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
12db0 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
12dc0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
12dd0 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
12de0 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
12df0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
12e00 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
12e10 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
12e20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
12e30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
12e40 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
12e50 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
12e60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
12e70 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
12e80 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
12e90 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
12ea0 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
12eb0 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
12ec0 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
12ed0 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
12ee0 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
12ef0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12f00 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
12f10 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
12f20 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
12f30 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
12f40 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
12f50 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
12f60 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
12f70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12f80 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
12f90 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
12fa0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
12fb0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
12fc0 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
12fd0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
12fe0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
12ff0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
13000 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
13010 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
13020 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
13030 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
13040 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
13050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
13060 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
13070 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
13080 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
13090 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
130a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
130b0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
130c0 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f n integer.** [co
130d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
130e0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 on] that determi
130f0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 nes.** what prop
13100 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 erty of SQLite i
13110 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 s to be configur
13120 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 ed. Subsequent
13130 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 arguments.** var
13140 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
13150 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f he [configuratio
13160 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
13170 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
13180 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
13190 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
131a0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
131b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
131c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
131d0 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
131e0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
131f0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
13200 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
13210 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
13220 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
13230 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
13240 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
13250 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
13260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
13270 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
13280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
13290 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
132a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 nnections.**.**
132b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
132c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
132d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
132e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
132f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
13300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
13310 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
13320 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
13330 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
13340 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
13350 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
13360 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
13370 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
13380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
13390 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
133a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
133b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
133c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
133d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
133e0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
133f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
13400 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
13410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
13420 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
13430 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
13440 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
13450 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
13460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13470 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
13480 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
13490 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
134a0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
134b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
134c0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
134d0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
134e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
134f0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
13500 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
13510 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
13520 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
13530 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
13540 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f int sqlite3_db_
13550 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
13560 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
13570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13580 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
13590 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
135a0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
135b0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
135c0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
135d0 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
135e0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
135f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
13600 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
13610 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
13620 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
13630 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
13640 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
13650 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
13660 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
13670 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
13680 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
13690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
136a0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
136b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
136c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
136d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
136e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
136f0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
13700 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
13710 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
13720 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
13730 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
13740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
13750 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
13760 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
13770 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
13780 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
13790 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
137a0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
137b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
137c0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
137d0 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
137e0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
137f0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
13800 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
13810 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
13820 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
13830 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
13840 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
13850 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
13860 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
13870 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
13880 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
13890 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
138a0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
138b0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
138c0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
138d0 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
138e0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
138f0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
13900 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
13910 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
13920 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
13930 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
13940 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
13950 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
13960 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
13970 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
13980 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
13990 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
139a0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
139b0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
139c0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
139d0 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
139e0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
139f0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
13a00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
13a10 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
13a20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
13a30 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
13a40 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
13a50 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
13a60 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
13a70 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
13a80 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
13a90 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
13aa0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
13ab0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
13ac0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
13ad0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
13ae0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
13af0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
13b00 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
13b10 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
13b20 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
13b30 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
13b40 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
13b50 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
13b60 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
13b70 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
13b80 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
13b90 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
13ba0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
13bb0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
13bc0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
13bd0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
13be0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
13bf0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
13c00 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
13c10 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
13c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13c30 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
13c40 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
13c50 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
13c60 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
13c70 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
13c80 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
13c90 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
13ca0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
13cb0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
13cc0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
13cd0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
13ce0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
13cf0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
13d00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
13d10 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
13d20 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
13d30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
13d40 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
13d50 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
13d60 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
13d70 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
13d80 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
13d90 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
13da0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
13db0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
13dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
13dd0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
13de0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
13df0 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
13e00 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
13e10 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
13e20 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
13e30 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
13e40 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
13e50 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
13e60 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
13e70 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
13e80 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
13e90 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
13ea0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
13eb0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
13ec0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
13ed0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
13ee0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
13ef0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
13f00 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
13f10 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
13f20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
13f30 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
13f40 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
13f50 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
13f60 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
13f70 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
13f80 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
13f90 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
13fa0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
13fb0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
13fc0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
13fd0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
13fe0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
13ff0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
14000 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
14010 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
14020 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
14030 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
14040 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
14050 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
14060 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
14070 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
14080 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
14090 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
140a0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
140b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
140c0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
140d0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
140e0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
140f0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
14100 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
14110 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
14120 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
14130 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
14140 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
14150 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
14160 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
14170 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
14180 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
14190 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
141a0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
141b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
141c0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
141d0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
141e0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
141f0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
14200 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
14210 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
14220 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
14230 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
14240 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
14250 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
14260 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
14270 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
14280 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
14290 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
142a0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
142b0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
142c0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
142d0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
142e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
142f0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
14300 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
14310 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
14320 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
14330 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
14340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
14350 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
14360 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
14370 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
14380 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
14390 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
143a0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
143b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
143c0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
143d0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
143e0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
143f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
14400 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
14410 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
14420 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
14430 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
14440 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
14450 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
14460 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
14470 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
14480 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
14490 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
144a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
144b0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
144c0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
144d0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
144e0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
144f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
14500 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
14510 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
14520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
14530 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
14540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
14550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
14560 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
14570 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
14580 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
14590 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
145a0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
145b0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
145c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
145d0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
145e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
145f0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
14600 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
14610 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
14620 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
14630 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
14640 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
14650 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
14660 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
14670 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
14680 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
14690 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
146a0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
146b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
146c0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
146d0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
146e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
146f0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
14700 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
14710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
14720 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
14730 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
14740 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
14750 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
14760 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
14770 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
14780 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
14790 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
147a0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
147b0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
147c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
147d0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
147e0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
147f0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
14800 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
14810 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
14820 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
14830 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
14840 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
14850 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
14860 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
14870 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14880 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
14890 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
148a0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
148b0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
148c0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
148d0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
148e0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
148f0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
14900 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
14910 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
14920 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
14930 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
14940 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
14950 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
14960 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
14970 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
14980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14990 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
149a0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
149b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
149c0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
149d0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
149e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
149f0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
14a00 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
14a10 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
14a20 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
14a30 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
14a40 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
14a50 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
14a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14a70 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
14a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
14a90 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
14aa0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
14ab0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
14ac0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
14ad0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
14ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
14af0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
14b00 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
14b10 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
14b20 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
14b30 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
14b40 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
14b50 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
14b60 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
14b70 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
14b80 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
14b90 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
14ba0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
14bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
14bc0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
14bd0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
14be0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
14bf0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
14c00 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
14c10 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
14c20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
14c30 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
14c40 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
14c50 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
14c60 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
14c70 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
14c80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
14c90 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
14ca0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
14cb0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
14cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
14cd0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
14ce0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
14cf0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14d00 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
14d10 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
14d20 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
14d30 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
14d40 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
14d50 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
14d60 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
14d70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
14d80 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
14d90 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
14da0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
14db0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
14dc0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
14dd0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
14de0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
14df0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
14e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
14e10 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
14e20 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
14e30 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
14e40 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
14e50 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
14e60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
14e70 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
14e80 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
14e90 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
14ea0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
14eb0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
14ec0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
14ed0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
14ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
14ef0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
14f00 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
14f10 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
14f20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
14f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
14f40 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
14f50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
14f60 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
14f70 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
14f80 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
14f90 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
14fa0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
14fb0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
14fc0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
14fd0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
14fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
14ff0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
15000 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
15010 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
15020 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
15030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
15040 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
15050 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
15060 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
15070 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
15080 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
15090 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
150a0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
150b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
150c0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
150d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
150e0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
150f0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
15100 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
15110 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
15120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
15130 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
15140 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
15150 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
15160 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
15170 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
15180 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
15190 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
151a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
151b0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
151c0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
151d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
151e0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
151f0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
15200 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
15210 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
15220 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
15230 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
15240 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
15250 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
15260 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
15270 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
15280 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
15290 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
152a0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
152b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
152c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
152d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
152e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
152f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
15300 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
15310 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
15320 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
15330 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
15340 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
15350 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
15360 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
15370 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
15380 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
15390 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
153a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
153b0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
153c0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
153d0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
153e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
153f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
15400 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
15410 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
15420 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
15430 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
15440 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
15450 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
15460 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
15470 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15480 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
15490 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
154a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
154b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
154c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
154d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
154e0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
154f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
15500 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
15510 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
15520 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
15530 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
15540 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
15550 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
15560 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
15570 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
15580 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 e disabled, the
15590 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 .** following SQ
155a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
155b0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
155c0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
155d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
155e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
155f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
15600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
15610 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
15620 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
15630 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
15640 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
15650 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
15660 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
15670 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
15680 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
15690 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
156a0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
156b0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
156c0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
156d0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
156e0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
156f0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
15700 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
15710 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
15720 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
15730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15740 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
15750 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
15760 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
15770 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
15780 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
15790 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
157a0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
157b0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
157c0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
157d0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
157e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
157f0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
15800 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
15810 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
15820 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
15830 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
15840 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
15850 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
15860 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
15870 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
15880 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
15890 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
158a0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
158b0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
158c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
158d0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
158e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
158f0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
15900 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
15910 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
15920 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
15930 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
15940 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
15950 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
15960 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 more than two s
15970 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 cratch buffers p
15980 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
15990 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
159a0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 t to twice the e
159b0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
159c0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
159d0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 s..** ^SQLite wi
159e0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ll never require
159f0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
15a00 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
15a10 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
15a20 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
15a30 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
15a40 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
15a50 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
15a60 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
15a70 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
15a80 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
15a90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
15aa0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
15ab0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
15ac0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
15ad0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
15ae0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a eeded.</dd>.**.*
15af0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15b00 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
15b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15b20 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
15b30 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
15b40 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
15b50 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
15b60 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
15b70 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
15b80 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
15b90 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
15ba0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
15bb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
15bc0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
15bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
15be0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
15bf0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
15c00 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
15c10 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
15c20 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
15c30 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
15c40 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
15c50 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
15c60 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
15c70 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
15c80 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
15c90 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
15ca0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
15cb0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
15cc0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
15cd0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
15ce0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
15cf0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
15d00 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
15d10 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
15d20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
15d30 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
15d40 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
15d50 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
15d60 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
15d70 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
15d80 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
15d90 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
15da0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
15db0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
15dc0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
15dd0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
15de0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
15df0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
15e00 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
15e10 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
15e20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
15e30 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
15e40 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
15e50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
15e60 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
15e70 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
15e80 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
15e90 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
15ea0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
15eb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
15ec0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
15ed0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
15ee0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
15ef0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
15f00 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
15f10 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
15f20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
15f30 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
15f40 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
15f50 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
15f60 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
15f70 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
15f80 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
15f90 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
15fa0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
15fb0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
15fc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
15fd0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
15fe0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
15ff0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
16000 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
16010 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
16020 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
16030 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
16040 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
16050 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
16060 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
16070 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
16080 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
16090 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
160a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
160b0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
160c0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
160d0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
160e0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
160f0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
16100 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
16110 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
16120 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
16130 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
16140 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
16150 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
16160 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
16170 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
16180 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
16190 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
161a0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
161b0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
161c0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
161d0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
161e0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
161f0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
16200 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
16210 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
16220 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
16230 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
16240 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
16250 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
16260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
16270 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
16280 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
16290 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
162a0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
162b0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
162c0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
162d0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
162e0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
162f0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
16300 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
16310 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
16320 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
16330 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
16340 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
16350 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
16360 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
16370 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
16380 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
16390 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
163a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
163b0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
163c0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
163d0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
163e0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
163f0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
16400 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
16410 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
16420 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
16430 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
16440 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
16450 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
16460 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
16470 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
16480 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
16490 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
164a0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
164b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
164c0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
164d0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
164e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
164f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
16500 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
16510 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
16520 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
16530 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
16540 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
16550 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
16560 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
16570 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
16580 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
16590 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a used in place.**
165a0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
165b0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
165c0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
165d0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
165e0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 f the.** content
165f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
16600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
16610 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
16620 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
16630 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
16640 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
16650 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
16660 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
16670 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
16680 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
16690 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
166a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
166b0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
166c0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
166d0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
166e0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
166f0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
16700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
16710 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
16720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16730 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
16740 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
16750 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
16760 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
16770 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
16780 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
16790 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
167a0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
167b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
167c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
167d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
167e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
167f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
16800 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
16810 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
16820 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
16830 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
16840 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
16850 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
16860 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
16870 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
16880 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
16890 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
168a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
168b0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
168c0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
168d0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
168e0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
168f0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
16900 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
16910 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
16920 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
16930 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
16940 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
16950 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
16960 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
16970 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
16980 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
16990 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
169a0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
169b0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
169c0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
169d0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
169e0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
169f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
16a00 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
16a10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16a20 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
16a30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
16a40 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
16a50 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
16a60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
16a70 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16a80 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
16a90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
16aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
16ab0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
16ac0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
16ad0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
16ae0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
16af0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
16b00 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
16b10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
16b20 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
16b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16b40 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
16b50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
16b60 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
16b70 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
16b80 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
16b90 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
16ba0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
16bb0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
16bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16bd0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
16be0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
16bf0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
16c00 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
16c10 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
16c20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
16c30 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
16c40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
16c50 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
16c60 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
16c70 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
16c80 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
16c90 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
16ca0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
16cb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16cc0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
16cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
16ce0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
16cf0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
16d00 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16d10 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
16d20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
16d30 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
16d40 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
16d50 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
16d60 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
16d70 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
16d80 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
16d90 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
16da0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d on.)^ ^SQLite m
16db0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
16dc0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 he.** object and
16dd0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 uses it for pag
16de0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 e cache memory a
16df0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e llocations.</dd>
16e00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
16e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
16e20 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
16e30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
16e40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
16e50 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
16e60 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
16e70 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
16e80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
16e90 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
16ea0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
16eb0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
16ec0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
16ed0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
16ee0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
16ef0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
16f00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
16f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
16f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16f30 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
16f40 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
16f50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
16f60 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
16f70 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 guments: a point
16f80 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 er to a.** funct
16f90 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 ion with a call
16fa0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 signature of voi
16fb0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 d(*)(void*,int,c
16fc0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a onst char*), .**
16fd0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 and a pointer t
16fe0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 o void. ^If the
16ff0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
17000 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 is not NULL, it
17010 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 is.** invoked b
17020 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 y [sqlite3_log()
17030 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 ] to process eac
17040 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e h logging event.
17050 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e ^If the.** fun
17060 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
17070 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 NULL, the [sqli
17080 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 te3_log()] inter
17090 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e face becomes a n
170a0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f o-op..** ^The vo
170b0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 id pointer that
170c0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 is the second ar
170d0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 gument to SQLITE
170e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a _CONFIG_LOG is.*
170f0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 * passed through
17100 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 as the first pa
17110 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
17120 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
17130 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
17140 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 ction whenever t
17150 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 hat function is
17160 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 invoked. ^The s
17170 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
17180 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 to.** the logger
17190 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 function is a c
171a0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 opy of the first
171b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
171c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
171d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 ** [sqlite3_log(
171e0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 )] call and is i
171f0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 ntended to be a
17200 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
17210 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 an.** [extended
17220 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 result code].
17230 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
17240 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 eter passed to t
17250 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 he logger is.**
17260 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 log message afte
17270 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 r formatting via
17280 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
17290 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 tf()]..** The SQ
172a0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 Lite logging int
172b0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
172c0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 entrant; the log
172d0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ger function.**
172e0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 supplied by the
172f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
17300 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 not invoke any
17310 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
17320 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d ..** In a multi-
17330 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
17340 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 tion, the applic
17350 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
17360 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
17370 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
17380 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a afe. </dd>.**.**
17390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
173a0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _URI]] <dt>SQLIT
173b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 E_CONFIG_URI.**
173c0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e <dd> This option
173d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
173e0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
173f0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 int. If non-zer
17400 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 o, then.** URI h
17410 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
17420 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 lly enabled. If
17430 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
17440 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 zero, then URI
17450 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 handling.** is g
17460 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
17470 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e . If URI handlin
17480 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
17490 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
174a0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 ames.** passed t
174b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
174c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
174d0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 n_v2()], [sqlite
174e0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
174f0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
17500 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
17510 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
17520 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
17530 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
17540 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
17550 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
17560 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
17570 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
17580 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
17590 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 ion is opened. I
175a0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
175b0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
175c0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
175d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
175e0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
175f0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
17600 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
17610 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
17620 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
17630 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 d. By default, U
17640 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
17650 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
17660 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
17670 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
17680 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
17690 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
176a0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
176b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
176c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
176d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b ONFIG_PCACHE]] [
176e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
176f0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 ETPCACHE]].** <d
17700 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17710 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 PCACHE and SQLIT
17720 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
17730 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 HE.** <dd> These
17740 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 options are obs
17750 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 olete and should
17760 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 not be used by
17770 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 new code..** The
17780 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 y are retained f
17790 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
177a0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 patibility but a
177b0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a re now no-ops..*
177c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
177d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
177e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
177f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
17800 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17810 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
17820 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
17830 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17840 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
17850 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
17860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
17870 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
17880 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
17890 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
178a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
178b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
178c0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
178d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
178e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
178f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
17900 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
17910 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
17920 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17930 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
17940 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
17950 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
17960 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
17970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
17980 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
17990 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
179a0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
179b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
179c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
179d0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
179e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
179f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
17a00 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
17a10 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
17a20 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
17a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
17a40 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
17a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
17a60 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
17a70 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
17a80 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
17a90 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
17aa0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
17ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17ac0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
17ad0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
17ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17af0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
17b00 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 14 /* no-o
17b10 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
17b20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
17b30 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e ACHE 15 /* n
17b40 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 o-op */.#define
17b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
17b60 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f G 16 /
17b70 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a * xFunc, void* *
17b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
17b90 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 _CONFIG_URI
17ba0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 17 /* int
17bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
17bd0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 18 /* sql
17be0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
17bf0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 ods2* */.#define
17c00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
17c10 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 ETPCACHE2 19
17c20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
17c30 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a e_methods2* */..
17c40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17c50 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
17c60 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
17c70 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
17c80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
17c90 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
17ca0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
17cb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
17cc0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
17cd0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
17ce0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
17cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
17d00 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
17d10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
17d20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
17d30 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
17d40 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
17d50 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
17d60 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
17d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
17d80 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
17d90 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
17da0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
17db0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
17dc0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
17dd0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
17de0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
17df0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
17e00 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
17e10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
17e20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
17e30 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
17e40 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
17e50 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
17e60 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
17e70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
17e80 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
17e90 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
17ea0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
17eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
17ec0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
17ed0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
17ee0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
17ef0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
17f00 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
17f10 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
17f20 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
17f30 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
17f40 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
17f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17f60 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
17f70 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
17f80 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
17f90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
17fa0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
17fb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
17fc0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
17fd0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
17fe0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
17ff0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
18000 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
18010 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
18020 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
18030 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
18040 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
18050 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
18060 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
18070 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
18090 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
180a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
180b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
180c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
180d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
180e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
180f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
18100 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
18110 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
18120 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
18130 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
18140 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
18150 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
18160 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
18170 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
18180 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
18190 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
181a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
181b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
181c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
181d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
181e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
181f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
18200 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
18210 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
18220 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
18230 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
18240 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
18250 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
18260 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
18270 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
18280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18290 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
182a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
182b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
182c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
182d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
182e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
182f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
18300 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
18310 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
18320 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
18330 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
18340 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
18350 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
18360 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
18370 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
18380 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
18390 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
183a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
183b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
183c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
183d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
183e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
183f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
18400 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
18410 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
18420 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
18430 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
18440 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
18450 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
18460 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
18470 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
18480 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
18490 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
184a0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
184b0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
184c0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
184d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
184e0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
184f0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
18500 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
18510 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
18520 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
18530 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
18540 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
18550 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
18560 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
18570 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
18580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
18590 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
185a0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
185b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
185c0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
185d0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
185e0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
185f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
18600 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
18610 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
18620 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
18630 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
18640 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
18650 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
18660 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
18670 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18680 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
18690 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
186a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
186b0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
186c0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
186d0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
186e0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
186f0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
18700 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
18710 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
18720 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
18730 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
18740 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
18750 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
18760 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
18770 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
18780 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
18790 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
187a0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
187b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
187c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
187d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
187e0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
187f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
18800 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
18810 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
18820 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
18830 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
18840 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
18850 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18860 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
18870 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
18880 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
18890 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
188a0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
188b0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
188c0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
188d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
188e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 G_LOOKASIDE
188f0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 1001 /* void*
18900 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
18910 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
18920 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 FIG_ENABLE_FKEY
18930 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 1002 /* int
18940 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
18950 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
18960 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
18970 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
18980 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t* */.../*.** CA
18990 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
189a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
189b0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
189c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
189d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
189e0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
189f0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
18a00 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
18a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
18a20 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
18a30 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
18a40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
18a50 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
18a60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
18a70 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
18a80 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
18a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
18aa0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
18ab0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c result_codes(sql
18ac0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 ite3*, int onoff
18ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
18ae0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 EF: Last Insert
18af0 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 Rowid.**.** ^Eac
18b00 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 h entry in an SQ
18b10 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 Lite table has a
18b20 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 unique 64-bit s
18b30 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 igned.** integer
18b40 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 key called the
18b50 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 [ROWID | "rowid"
18b60 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 ]. ^The rowid is
18b70 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c always availabl
18b80 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 e.** as an undec
18b90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d lared column nam
18ba0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f ed ROWID, OID, o
18bb0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e r _ROWID_ as lon
18bc0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 g as those.** na
18bd0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f mes are not also
18be0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 used by explici
18bf0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
18c00 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 umns. ^If.** the
18c10 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
18c20 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 umn of type [INT
18c30 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
18c40 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 ] then that colu
18c50 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 mn.** is another
18c60 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 alias for the r
18c70 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 owid..**.** ^Thi
18c80 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
18c90 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
18ca0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18cb0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
18cc0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 INSERT] into the
18cd0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 database from t
18ce0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
18cf0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 nection].** in t
18d00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18d10 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 t. ^As of SQLit
18d20 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c e version 3.7.7,
18d30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a this routines.*
18d40 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 * records the la
18d50 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 st insert rowid
18d60 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 of both ordinary
18d70 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 tables and [vir
18d80 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a tual tables]..**
18d90 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 ^If no successf
18da0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 ul [INSERT]s.**
18db0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
18dc0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 ed on that datab
18dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
18de0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
18df0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 ..**.** ^(If an
18e00 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 [INSERT] occurs
18e10 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
18e20 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 or within a [vi
18e30 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 rtual table].**
18e40 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 method, then thi
18e50 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 s routine will r
18e60 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 eturn the [rowid
18e70 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 ] of the inserte
18e80 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 d.** row as long
18e90 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 as the trigger
18ea0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 or virtual table
18eb0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 method is runni
18ec0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 ng..** But once
18ed0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
18ee0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 irtual table met
18ef0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 hod ends, the va
18f00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a lue returned .**
18f10 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
18f20 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 reverts to what
18f30 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 it was before t
18f40 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
18f50 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d rtual.** table m
18f60 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a ethod began.)^.*
18f70 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 *.** ^An [INSERT
18f80 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 ] that fails due
18f90 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 to a constraint
18fa0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f violation is no
18fb0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 t a.** successfu
18fc0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 l [INSERT] and d
18fd0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
18fe0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
18ff0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 d by this.** rou
19000 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 tine. ^Thus INS
19010 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 ERT OR FAIL, INS
19020 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 ERT OR IGNORE, I
19030 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 NSERT OR ROLLBAC
19040 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 K,.** and INSERT
19050 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e OR ABORT make n
19060 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 o changes to the
19070 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
19080 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
19090 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 when their inse
190a0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 rtion fails. ^(
190b0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
190c0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
190d0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
190e0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
190f0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
19100 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
19110 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
19120 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
19130 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
19140 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
19150 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
19160 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
19170 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
19180 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
19190 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
191a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e his interface.)^
191b0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 .**.** ^For the
191c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 purposes of this
191d0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e routine, an [IN
191e0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 SERT] is conside
191f0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 red to.** be suc
19200 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 cessful even if
19210 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 it is subsequent
19220 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
19230 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
19240 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c ion is accessibl
19250 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 e to SQL stateme
19260 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b nts via the.** [
19270 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
19280 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e d() SQL function
19290 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
192a0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 parate thread pe
192b0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e rforms a new [IN
192c0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d SERT] on the sam
192d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
192e0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 nnection while t
192f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
19300 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
19310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
19320 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 running and thus
19330 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 changes the las
19340 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
19350 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 ,.** then the va
19360 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
19370 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
19380 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
19390 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c .** unpredictabl
193a0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 e and might not
193b0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 equal either the
193c0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a old or the new.
193d0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b ** last insert [
193e0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 rowid]..*/.SQLIT
193f0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
19400 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 t64 sqlite3_last
19410 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
19420 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
19430 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 CAPI3REF: Count
19440 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f The Number Of Ro
19450 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
19460 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
19470 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
19480 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 ber of database
19490 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 rows that were c
194a0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 hanged.** or ins
194b0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 erted or deleted
194c0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
194d0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
194e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
194f0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 on the [databas
19500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
19510 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ecified by the f
19520 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
19530 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 ** ^(Only change
19540 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
19550 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
19560 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b the [INSERT], [
19570 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b UPDATE],.** or [
19580 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
19590 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
195a0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
195b0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
195c0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 riggers or [fore
195d0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
195e0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
195f0 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b .)^ Use the.** [
19600 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
19610 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f anges()] functio
19620 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f n to find the to
19630 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 tal number of ch
19640 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 anges.** includi
19650 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 ng changes cause
19660 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e d by triggers an
19670 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 d foreign key ac
19680 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 tions..**.** ^Ch
19690 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 anges to a view
196a0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 that are simulat
196b0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 ed by an [INSTEA
196c0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a D OF trigger].**
196d0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
196e0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 . Only real tab
196f0 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 le changes are c
19700 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ounted..**.** ^(
19710 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 A "row change" i
19720 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 s a change to a
19730 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 single row of a
19740 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 single table.**
19750 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 caused by an INS
19760 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 ERT, DELETE, or
19770 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 UPDATE statement
19780 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 . Rows that.**
19790 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 are changed as s
197a0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b ide effects of [
197b0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 REPLACE] constra
197c0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a int resolution,.
197d0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f ** rollback, ABO
197e0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b RT processing, [
197f0 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 DROP TABLE], or
19800 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 by any other.**
19810 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f mechanisms do no
19820 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 t count as direc
19830 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e t row changes.)^
19840 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 .**.** A "trigge
19850 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 r context" is a
19860 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 scope of executi
19870 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 on that begins a
19880 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 nd.** ends with
19890 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 the script of a
198a0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
198b0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 | trigger]. .**
198c0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 Most SQL stateme
198d0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 nts are.** evalu
198e0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 ated outside of
198f0 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 any trigger. Th
19900 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c is is the "top l
19910 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 evel".** trigger
19920 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 context. If a
19930 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 trigger fires fr
19940 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
19950 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 , a.** new trigg
19960 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e er context is en
19970 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 tered for the du
19980 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f ration of that o
19990 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 ne.** trigger.
199a0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 Subtriggers crea
199b0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 te subcontexts f
199c0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f or their duratio
199d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e n..**.** ^Callin
199e0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
199f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
19a00 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
19a10 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
19a20 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
19a30 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
19a40 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
19a50 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
19a60 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 mber of direct r
19a70 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ow changes in th
19a80 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 e.** most recent
19a90 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
19aa0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
19ab0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
19ac0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 same.** trigger
19ad0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e context..**.** ^
19ae0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 Thus, when calle
19af0 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c d from the top l
19b00 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 evel, this funct
19b10 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
19b20 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 ** number of cha
19b30 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
19b40 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 recent INSERT,
19b50 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
19b60 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f E.** that also o
19b70 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 ccurred at the t
19b80 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 op level. ^(Wit
19b90 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
19ba0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 a trigger,.** th
19bb0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
19bc0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 s() interface ca
19bd0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 n be called to f
19be0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
19bf0 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 f.** changes in
19c00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
19c10 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 y completed INSE
19c20 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
19c30 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
19c40 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f nt within the bo
19c50 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 dy of the same t
19c60 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 rigger..** Howev
19c70 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 er, the number r
19c80 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 eturned does not
19c90 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 include changes
19ca0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 .** caused by su
19cb0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 btriggers since
19cc0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 those have their
19cd0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a own context.)^.
19ce0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 **.** See also t
19cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 he [sqlite3_tota
19d00 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 l_changes()] int
19d10 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
19d20 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
19d30 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
19d40 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
19d50 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
19d60 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
19d70 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
19d80 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
19d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19da0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
19db0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
19dc0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
19dd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
19de0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 d.** is unpredic
19df0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
19e00 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c aningful..*/.SQL
19e10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
19e20 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 te3_changes(sqli
19e30 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
19e40 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 PI3REF: Total Nu
19e50 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
19e60 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ified.**.** ^Thi
19e70 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
19e80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
19e90 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 row changes cau
19ea0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c sed by [INSERT],
19eb0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 .** [UPDATE] or
19ec0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
19ed0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 nts since the [d
19ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19ef0 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a on] was opened..
19f00 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 ** ^(The count r
19f10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
19f20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
19f30 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
19f40 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 changes.** from
19f50 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 all [CREATE TRIG
19f60 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 GER | trigger] c
19f70 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e ontexts and chan
19f80 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b ges made by.** [
19f90 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
19fa0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a ons]. However,.*
19fb0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 * the count does
19fc0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 not include cha
19fd0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 nges used to imp
19fe0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d lement [REPLACE]
19ff0 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a constraints,.**
1a000 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 do rollbacks or
1a010 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e ABORT processin
1a020 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c g, or [DROP TABL
1a030 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 E] processing.
1a040 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 The.** count doe
1a050 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f s not include ro
1a060 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 ws of views that
1a070 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 fire an [INSTEA
1a080 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a D OF trigger],.*
1a090 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 * though if the
1a0a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
1a0b0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 er makes changes
1a0c0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f of its own, tho
1a0d0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 se changes .** a
1a0e0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a re counted.)^.**
1a0f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f ^The sqlite3_to
1a100 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 tal_changes() fu
1a110 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 nction counts th
1a120 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f e changes as soo
1a130 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 n as.** the stat
1a140 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 ement that makes
1a150 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 them is complet
1a160 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 ed (when the sta
1a170 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a tement handle.**
1a180 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 is passed to [s
1a190 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1a1a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
1a1b0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 lize()])..**.**
1a1c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
1a1d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
1a1e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a interface, the.
1a1f0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 ** [count_change
1a200 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 s pragma], and t
1a210 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 he [total_change
1a220 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
1a230 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
1a240 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
1a250 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
1a260 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
1a270 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
1a280 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f hile [sqlite3_to
1a290 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
1a2a0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
1a2b0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
1a2c0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 rned is unpredic
1a2d0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 table and not me
1a2e0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c aningful..*/.SQL
1a2f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1a300 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1a310 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
1a320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
1a330 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
1a340 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a unning Query.**.
1a350 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1a360 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
1a370 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
1a380 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
1a390 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
1a3a0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
1a3b0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
1a3c0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
1a3d0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
1a3e0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
1a3f0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
1a400 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
1a410 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
1a420 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
1a430 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
1a440 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
1a450 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
1a460 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
1a470 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
1a480 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
1a490 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
1a4a0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
1a4b0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
1a4c0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
1a4d0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
1a4e0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
1a4f0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
1a500 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
1a510 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
1a520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a530 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
1a540 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
1a550 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
1a560 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1a570 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
1a580 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
1a590 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
1a5a0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
1a5b0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
1a5c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1a5d0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
1a5e0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
1a5f0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
1a600 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
1a610 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
1a620 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
1a630 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
1a640 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
1a650 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
1a660 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
1a670 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
1a680 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
1a690 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
1a6a0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
1a6b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
1a6c0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
1a6d0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
1a6e0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
1a6f0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
1a700 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
1a710 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
1a720 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
1a730 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
1a740 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
1a750 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
1a760 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
1a770 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
1a780 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1a790 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
1a7a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a7b0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
1a7c0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
1a7d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1a7e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1a7f0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
1a800 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
1a810 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
1a820 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
1a830 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
1a840 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
1a850 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
1a860 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
1a870 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
1a880 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1a890 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
1a8a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1a8b0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
1a8c0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
1a8d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
1a8e0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
1a8f0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
1a900 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
1a910 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
1a920 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
1a930 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1a940 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
1a950 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
1a960 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
1a970 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
1a980 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
1a990 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
1a9a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
1a9b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
1a9c0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
1a9d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
1a9e0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
1a9f0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
1aa00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
1aa10 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
1aa20 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
1aa30 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
1aa40 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
1aa50 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
1aa60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1aa70 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
1aa80 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
1aa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1aaa0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
1aab0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
1aac0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
1aad0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1aae0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
1aaf0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
1ab00 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
1ab10 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
1ab20 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
1ab30 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
1ab40 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
1ab50 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
1ab60 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
1ab70 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
1ab80 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
1ab90 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
1aba0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
1abb0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
1abc0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
1abd0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
1abe0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
1abf0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
1ac00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
1ac10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
1ac20 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
1ac30 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
1ac40 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
1ac50 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
1ac60 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
1ac70 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
1ac80 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
1ac90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
1aca0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
1acb0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
1acc0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
1acd0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
1ace0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
1acf0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
1ad00 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
1ad10 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
1ad20 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
1ad30 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
1ad40 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
1ad50 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
1ad60 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
1ad70 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
1ad80 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
1ad90 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
1ada0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
1adb0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
1adc0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
1add0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
1ade0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
1adf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1ae00 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
1ae10 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
1ae20 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
1ae30 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
1ae40 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
1ae50 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
1ae60 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
1ae70 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
1ae80 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
1ae90 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
1aea0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
1aeb0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
1aec0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
1aed0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
1aee0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
1aef0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
1af00 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
1af10 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
1af20 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
1af30 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
1af40 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
1af50 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
1af60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
1af70 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
1af80 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
1af90 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
1afa0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
1afb0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
1afc0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
1afd0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
1afe0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
1aff0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
1b000 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
1b010 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
1b020 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
1b030 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1b040 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1b050 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1b060 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
1b070 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
1b080 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
1b090 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
1b0a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
1b0b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
1b0c0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
1b0d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c te order..*/.SQL
1b0e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1b0f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
1b100 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 st char *sql);.S
1b110 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1b120 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1b130 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
1b140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1b150 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
1b160 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
1b170 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
1b180 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 rors.**.** ^This
1b190 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1b1a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1b1b0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
1b1c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
1b1d0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
1b1e0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
1b1f0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
1b200 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
1b210 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
1b220 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
1b230 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 .** ^If the busy
1b240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
1b250 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f L, then [SQLITE_
1b260 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
1b270 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
1b280 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1b290 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
1b2a0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
1b2b0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 lock. ^If the
1b2c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a busy callback.**
1b2d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
1b2e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1b2f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1b300 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
1b310 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1b320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1b330 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c o the busy handl
1b340 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 er is a copy of
1b350 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 the void* pointe
1b360 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 r which.** is th
1b370 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1b380 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 to sqlite3_busy
1b390 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 _handler(). ^Th
1b3a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1b3b0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 t to.** the busy
1b3c0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1b3d0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
1b3e0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
1b3f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
1b400 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
1b410 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
1b420 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
1b430 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
1b440 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
1b450 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
1b460 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
1b470 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
1b480 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
1b490 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
1b4a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
1b4b0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 R_BLOCKED] is re
1b4c0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 turned..** ^If t
1b4d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
1b4e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
1b4f0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
1b500 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
1b510 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
1b520 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 se for reading a
1b530 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
1b540 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
1b550 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
1b560 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
1b570 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
1b580 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
1b590 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
1b5a0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
1b5b0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 ention. ^If SQLi
1b5c0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 te determines th
1b5d0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 at invoking the
1b5e0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 busy.** handler
1b5f0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 could result in
1b600 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 a deadlock, it w
1b610 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 ill go ahead and
1b620 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1b630 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c BUSY].** or [SQL
1b640 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
1b650 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e D] instead of in
1b660 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 voking the busy
1b670 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 handler..** Cons
1b680 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 ider a scenario
1b690 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 where one proces
1b6a0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1b6b0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a ead lock that.**
1b6c0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f it is trying to
1b6d0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 promote to a re
1b6e0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a served lock and.
1b6f0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 ** a second proc
1b700 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ess is holding a
1b710 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 reserved lock t
1b720 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 hat it is trying
1b730 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
1b740 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c o an exclusive l
1b750 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 ock. The first
1b760 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 process cannot p
1b770 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 roceed.** becaus
1b780 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1b790 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e by the second an
1b7a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f d the second pro
1b7b0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 cess cannot.** p
1b7c0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 roceed because i
1b7d0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
1b7e0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 the first. If b
1b7f0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a oth processes.**
1b800 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 invoke the busy
1b810 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 handlers, neith
1b820 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 er will make any
1b830 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 progress. Ther
1b840 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 efore,.** SQLite
1b850 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1b860 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 _BUSY] for the f
1b870 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f irst process, ho
1b880 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a ping that this.*
1b890 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 * will induce th
1b8a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
1b8b0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 to release its r
1b8c0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c ead lock and all
1b8d0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 ow.** the second
1b8e0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 process to proc
1b8f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1b900 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c default busy cal
1b910 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a lback is NULL..*
1b920 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
1b930 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 E_BUSY] error is
1b940 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 converted to [S
1b950 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
1b960 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c KED].** when SQL
1b970 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 ite is in the mi
1b980 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 ddle of a large
1b990 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 transaction wher
1b9a0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 e all the.** cha
1b9b0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 nges will not fi
1b9c0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 t into the in-me
1b9d0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c mory cache. SQL
1b9e0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 ite will.** alre
1b9f0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 ady hold a RESER
1ba00 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 VED lock on the
1ba10 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 database file, b
1ba20 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 ut it needs.** t
1ba30 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c o promote this l
1ba40 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 ock to EXCLUSIVE
1ba50 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 so that it can
1ba60 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 spill cache.** p
1ba70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 ages into the da
1ba80 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 tabase file with
1ba90 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 out harm to conc
1baa0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 urrent.** reader
1bab0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e s. ^If it is un
1bac0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 able to promote
1bad0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 the lock, then t
1bae0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 he in-memory.**
1baf0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 cache will be le
1bb00 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 ft in an inconsi
1bb10 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 stent state and
1bb20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 so the error.**
1bb30 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 code is promoted
1bb40 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 from the relati
1bb50 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c vely benign [SQL
1bb60 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 ITE_BUSY] to.**
1bb70 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 the more severe
1bb80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
1bb90 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 OCKED]. ^This e
1bba0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 rror code promot
1bbb0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e ion.** forces an
1bbc0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 automatic rollb
1bbd0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 ack of the chang
1bbe0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 es. See the.**
1bbf0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 <a href="/cvstra
1bc00 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
1bc10 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
1bc20 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
1bc30 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
1bc40 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
1bc50 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
1bc60 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
1bc70 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
1bc80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 nt..**.** ^(Ther
1bc90 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1bca0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1bcb0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1bcc0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1bcd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1bce0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1bcf0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1bd00 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1bd10 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1bd20 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1bd30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1bd40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1bd50 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 ** will also set
1bd60 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 or clear the bu
1bd70 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a sy handler..**.*
1bd80 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 * The busy callb
1bd90 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 ack should not t
1bda0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 ake any actions
1bdb0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 which modify the
1bdc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1bdd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1bde0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
1bdf0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 ndler. Any such
1be00 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 actions.** resu
1be10 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
1be20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a behavior..** .**
1be30 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
1be40 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
1be50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1be60 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
1be70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1be80 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
1be90 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1bea0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1beb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
1bec0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1bed0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
1bee0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
1bef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
1bf00 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
1bf10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1bf20 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
1bf30 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1bf40 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
1bf50 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
1bf60 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
1bf70 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
1bf80 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
1bf90 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
1bfa0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
1bfb0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
1bfc0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
1bfd0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1bfe0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
1bff0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
1c000 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
1c010 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1c020 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1c030 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
1c040 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
1c050 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
1c060 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
1c070 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
1c080 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
1c090 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
1c0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
1c0b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1c0c0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
1c0d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
1c0e0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
1c0f0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
1c100 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
1c110 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
1c120 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
1c130 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
1c140 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
1c150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c160 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 on] any any give
1c170 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
1c180 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1c190 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
1c1a0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
1c1b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1c1c0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
1c1d0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
1c1e0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
1c1f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
1c200 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 cleared.)^.*/.S
1c210 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
1c220 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1c230 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
1c240 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
1c250 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
1c260 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
1c270 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
1c280 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1c290 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1c2a0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1c2b0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1c2c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1c2d0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1c2e0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1c2f0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1c300 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1c310 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1c320 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1c330 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1c340 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1c350 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1c360 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1c370 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1c380 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1c390 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1c3a0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1c3b0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1c3c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1c3d0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1c3e0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1c3f0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1c400 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1c410 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1c420 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1c430 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1c440 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1c450 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1c460 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1c470 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1c480 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1c490 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1c4a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1c4b0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1c4c0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1c4d0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1c4e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1c4f0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1c500 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1c510 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1c520 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1c530 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1c540 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1c550 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1c560 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1c570 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1c580 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1c590 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1c5a0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1c5b0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1c5c0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1c5d0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1c5e0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1c5f0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1c600 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1c610 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1c620 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1c630 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1c640 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1c650 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1c660 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1c670 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1c680 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1c690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1c6a0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1c6b0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1c6c0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1c6d0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1c6e0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1c6f0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1c700 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1c710 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1c720 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1c730 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1c740 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1c750 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1c760 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1c770 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1c780 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1c790 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1c7b0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1c7c0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1c7d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1c7e0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1c7f0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1c800 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1c810 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1c820 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1c830 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1c840 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1c850 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1c860 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1c870 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1c880 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1c890 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1c8a0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1c8b0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1c8c0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1c8d0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1c8e0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1c8f0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1c900 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1c910 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1c920 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1c930 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1c940 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1c950 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1c960 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1c970 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1c980 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1c990 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1c9a0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1c9b0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1c9c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1c9d0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1c9e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1c9f0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1ca00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1ca10 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1ca20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1ca30 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1ca40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1ca50 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1ca60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1ca70 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1ca80 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1ca90 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1caa0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1cab0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1cac0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1cad0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1cae0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1caf0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1cb00 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1cb10 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1cb20 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1cb30 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1cb40 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1cb50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1cb60 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1cb70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1cb80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1cb90 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1cba0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1cbb0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1cbc0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1cbd0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1cbe0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1cbf0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1cc00 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1cc10 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1cc20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1cc30 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1cc40 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1cc50 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1cc60 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1cc70 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1cc80 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1cc90 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1cca0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1ccb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1ccc0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1ccd0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1cce0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1ccf0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1cd00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1cd10 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1cd20 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1cd30 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1cd40 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1cd50 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1cd60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1cd70 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1cd80 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1cd90 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1cda0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1cdb0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1cdc0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1cdd0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1cde0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1cdf0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1ce00 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1ce10 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1ce20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1ce30 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1ce40 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1ce50 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1ce60 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1ce70 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1ce80 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1ce90 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1cea0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1ceb0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f g()]..*/.SQLITE_
1cec0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1ced0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c get_table(. sql
1cee0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1cef0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
1cf00 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
1cf10 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
1cf20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
1cf30 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 valuated */. ch
1cf40 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c ar ***pazResult,
1cf50 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f /* Results o
1cf60 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 f the query */.
1cf70 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 int *pnRow,
1cf80 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1cf90 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 of result rows
1cfa0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1cfb0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c int *pnColumn,
1cfc0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1cfd0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 r of result colu
1cfe0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 mns written here
1cff0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 */. char **pzE
1d000 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 rrmsg /* E
1d010 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
1d020 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 here */.);.SQLI
1d030 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
1d040 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
1d050 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
1d060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1d070 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
1d080 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
1d090 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1d0a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
1d0b0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
1d0c0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
1d0d0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
1d0e0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
1d0f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
1d100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1d110 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
1d120 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1d130 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
1d140 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
1d150 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
1d160 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
1d170 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
1d180 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
1d190 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
1d1a0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
1d1b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
1d1c0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
1d1d0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
1d1e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1d1f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
1d200 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
1d210 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
1d220 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
1d230 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
1d240 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
1d250 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
1d260 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
1d270 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
1d280 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
1d290 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
1d2a0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
1d2b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
1d2c0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
1d2d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
1d2e0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
1d2f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1d300 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
1d310 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
1d320 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
1d330 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
1d340 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
1d350 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
1d360 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
1d370 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
1d380 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 printf().)^ Thi
1d390 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
1d3a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
1d3b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
1d3c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
1d3d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
1d3e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
1d3f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 ^(Note also th
1d400 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 at sqlite3_snpri
1d410 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 ntf().** returns
1d420 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
1d430 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 s buffer instead
1d440 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
1d450 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 f.** characters
1d460 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e actually written
1d470 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 into the buffer
1d480 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 .)^ We admit th
1d490 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 at.** the number
1d4a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 of characters w
1d4b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 ritten would be
1d4c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 a more useful re
1d4d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 turn.** value bu
1d4e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e t we cannot chan
1d4f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ge the implement
1d500 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
1d510 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e _snprintf().** n
1d520 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ow without break
1d530 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ing compatibilit
1d540 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e y..**.** ^As lon
1d550 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
1d560 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
1d570 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
1d580 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1d590 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
1d5a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
1d5b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
1d5c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 nated. ^The fir
1d5d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
1d5e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
1d5f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
1d600 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
1d610 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
1d620 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1d630 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
1d640 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
1d650 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
1d660 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
1d670 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
1d680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1d690 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 ite3_vsnprintf()
1d6a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 routine is a va
1d6b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 rargs version of
1d6c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1d6d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 f()..**.** These
1d6e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
1d6f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
1d700 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
1d710 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
1d720 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
1d730 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
1d740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
1d750 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
1d760 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
1d770 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
1d780 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
1d790 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
1d7a0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
1d7b0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
1d7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 ..**.** ^(The %q
1d7d0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1d7e0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
1d7f0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
1d800 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ul-terminated.**
1d810 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 string from the
1d820 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 argument list.
1d830 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 But %q also dou
1d840 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 bles every '\''
1d850 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 character..** %q
1d860 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 is designed for
1d870 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 use inside a st
1d880 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 ring literal.)^
1d890 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 By doubling eac
1d8a0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 h '\''.** charac
1d8b0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 ter it escapes t
1d8c0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e hat character an
1d8d0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 d allows it to b
1d8e0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a e inserted into.
1d8f0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a ** the string..*
1d900 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 *.** For example
1d910 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 , assume the str
1d920 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 ing variable zTe
1d930 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 xt contains text
1d940 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1d950 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1d960 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1d970 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
1d980 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
1d990 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1d9a0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
1d9b0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
1d9c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
1d9d0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
1d9e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1d9f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1da00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
1da10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
1da20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
1da30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
1da40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1da50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1da60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1da70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1da80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1da90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
1daa0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
1dab0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
1dac0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
1dad0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
1dae0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
1daf0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
1db00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
1db10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1db20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
1db30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
1db40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
1db50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
1db60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1db70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
1db80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
1db90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
1dba0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
1dbb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
1dbc0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
1dbd0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
1dbe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1dbf0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1dc00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1dc10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
1dc20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
1dc30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1dc40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
1dc50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
1dc60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
1dc70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
1dc80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a ule you should.*
1dc90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 * always use %q
1dca0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
1dcb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
1dcc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
1dcd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e literal..**.** ^
1dce0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 (The %Q option w
1dcf0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 orks like %q exc
1dd00 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 ept it also adds
1dd10 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 single quotes a
1dd20 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 round.** the out
1dd30 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 side of the tota
1dd40 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 l string. Addit
1dd50 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 ionally, if the
1dd60 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
1dd70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .** argument lis
1dd80 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
1dd90 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 ter, %Q substitu
1dda0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 tes the text "NU
1ddb0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 LL" (without.**
1ddc0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 single quotes).)
1ddd0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 ^ So, for examp
1dde0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 le, one could sa
1ddf0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 y:.**.** <blockq
1de00 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
1de10 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
1de20 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
1de30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
1de40 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 ALUES(%Q)", zTex
1de50 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
1de60 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
1de70 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
1de80 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
1de90 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1dea0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1deb0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c e code above wil
1dec0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 l render a corre
1ded0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ct SQL statement
1dee0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 in the zSQL.**
1def0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 variable even if
1df00 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 the zText varia
1df10 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ble is a NULL po
1df20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 inter..**.** ^(T
1df30 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
1df40 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
1df50 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
1df60 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
1df70 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
1df80 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
1df90 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
1dfa0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
1dfb0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
1dfc0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
1dfd0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
1dfe0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 ring.)^.*/.SQLIT
1dff0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
1e000 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
1e010 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 t char*,...);.SQ
1e020 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
1e030 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1e040 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1e050 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 list);.SQLITE_AP
1e060 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1e070 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1e080 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1e090 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
1e0a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
1e0b0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1e0c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1e0d0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1e0e0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1e0f0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1e100 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1e110 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1e120 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1e130 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1e140 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1e150 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1e160 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1e170 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1e180 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1e190 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1e1a0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1e1b0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1e1c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1e1d0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1e1e0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1e1f0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1e200 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1e210 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1e220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1e230 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1e240 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1e250 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1e260 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1e270 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1e280 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1e290 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1e2a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1e2b0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1e2c0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1e2d0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1e2e0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1e2f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1e300 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1e310 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1e320 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1e330 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1e340 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1e350 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1e360 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1e370 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
1e380 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 sqlite3_free() w
1e390 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 ith a pointer pr
1e3a0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
1e3b0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
1e3c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
1e3d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
1e3e0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f leases that memo
1e3f0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 ry so.** that it
1e400 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 might be reused
1e410 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
1e420 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 free() routine i
1e430 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 s.** a no-op if
1e440 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1e450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
1e460 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 Passing a NULL p
1e470 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c ointer.** to sql
1e480 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 ite3_free() is h
1e490 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 armless. After
1e4a0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d being freed, mem
1e4b0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 ory.** should ne
1e4c0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f ither be read no
1e4d0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e r written. Even
1e4e0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 reading previou
1e4f0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d sly freed.** mem
1e500 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ory might result
1e510 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 in a segmentati
1e520 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 on fault or othe
1e530 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a r severe error..
1e540 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 ** Memory corrup
1e550 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 tion, a segmenta
1e560 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f tion fault, or o
1e570 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1e580 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c r.** might resul
1e590 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 t if sqlite3_fre
1e5a0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 e() is called wi
1e5b0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f th a non-NULL po
1e5c0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 inter that.** wa
1e5d0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 s not obtained f
1e5e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c rom sqlite3_mall
1e5f0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1e600 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a realloc()..**.**
1e610 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ^(The sqlite3_r
1e620 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 ealloc() interfa
1e630 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 ce attempts to r
1e640 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 esize a.** prior
1e650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1e660 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 on to be at leas
1e670 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 t N bytes, where
1e680 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 N is the.** sec
1e690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
1e6a0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 The memory alloc
1e6b0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 ation to be resi
1e6c0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 zed is the first
1e6d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e .** parameter.)^
1e6e0 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 ^ If the first
1e6f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1e700 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a ite3_realloc().*
1e710 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
1e720 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 ter then its beh
1e730 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 avior is identic
1e740 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a al to calling.**
1e750 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1e760 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 N) where N is th
1e770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1e780 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1e790 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 alloc()..** ^If
1e7a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1e7b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1e7c0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 realloc() is zer
1e7d0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 o or.** negative
1e7e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
1e7f0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 or is exactly th
1e800 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e e same as callin
1e810 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 g.** sqlite3_fre
1e820 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 e(P) where P is
1e830 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1e840 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1e850 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 ealloc()..** ^sq
1e860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1e870 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1e880 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
1e890 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
1e8a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1e8b0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
1e8c0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 if sufficient me
1e8d0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 mory is unavaila
1e8e0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 ble..** ^If M is
1e8f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
1e900 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1e910 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 n, then min(N,M)
1e920 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 bytes.** of the
1e930 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1e940 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 n are copied int
1e950 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
1e960 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e of buffer return
1e970 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1e980 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 _realloc() and t
1e990 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1e9a0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1e9b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1e9c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e lloc() returns N
1e9d0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ULL, then the pr
1e9e0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ior allocation.*
1e9f0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a * is not freed..
1ea00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
1ea10 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 y returned by sq
1ea20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 lite3_malloc() a
1ea30 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c nd sqlite3_reall
1ea40 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 oc().** is alway
1ea50 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 s aligned to at
1ea60 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 least an 8 byte
1ea70 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 boundary, or to
1ea80 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e a.** 4 byte boun
1ea90 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c dary if the [SQL
1eaa0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e ITE_4_BYTE_ALIGN
1eab0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 ED_MALLOC] compi
1eac0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
1ead0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n is used..**.**
1eae0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
1eaf0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
1eb00 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
1eb10 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
1eb20 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
1eb30 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
1eb40 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
1eb50 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
1eb60 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
1eb70 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
1eb80 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
1eb90 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
1eba0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
1ebb0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
1ebc0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
1ebd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
1ebe0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
1ebf0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 .** The Windows
1ec00 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
1ec10 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 er calls.** the
1ec20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
1ec30 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
1ec40 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
1ec50 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
1ec60 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
1ec70 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
1ec80 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
1ec90 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
1eca0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
1ecb0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
1ecc0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
1ecd0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
1ece0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
1ecf0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 on errors are de
1ed00 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 tected, but.** t
1ed10 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 hey are reported
1ed20 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 back as [SQLITE
1ed30 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a _CANTOPEN] or.**
1ed40 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 [SQLITE_IOERR]
1ed50 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c rather than [SQL
1ed60 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a ITE_NOMEM]..**.*
1ed70 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 * The pointer ar
1ed80 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 guments to [sqli
1ed90 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 te3_free()] and
1eda0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1edb0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 ()].** must be e
1edc0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c ither NULL or el
1edd0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 se pointers obta
1ede0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f ined from a prio
1edf0 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 r.** invocation
1ee00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
1ee10 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
1ee20 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 3_realloc()] tha
1ee30 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 t have.** not ye
1ee40 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e t been released.
1ee50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
1ee60 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
1ee70 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e read or write an
1ee80 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 y part of.** a b
1ee90 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 lock of memory a
1eea0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
1eeb0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a released using.
1eec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1eed0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1eee0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 realloc()]..*/.S
1eef0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
1ef00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 sqlite3_malloc(i
1ef10 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1ef20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
1ef30 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
1ef40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
1ef50 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
1ef60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1ef70 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
1ef80 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 Allocator Statis
1ef90 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 tics.**.** SQLit
1efa0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 e provides these
1efb0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 two interfaces
1efc0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e for reporting on
1efd0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f the status.** o
1efe0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
1eff0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 alloc()], [sqlit
1f000 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 e3_free()], and
1f010 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1f020 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c ()].** routines,
1f030 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 which form the
1f040 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
1f050 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
1f060 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 stem..**.** ^The
1f070 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1f080 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 _used()] routine
1f090 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1f0a0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 ber of bytes.**
1f0b0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e of memory curren
1f0c0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 tly outstanding
1f0d0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f (malloced but no
1f0e0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 t freed)..** ^Th
1f0f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
1f100 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 y_highwater()] r
1f110 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1f120 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 he maximum.** va
1f130 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
1f140 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 memory_used()] s
1f150 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 ince the high-wa
1f160 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 ter mark.** was
1f170 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 last reset. ^Th
1f180 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
1f190 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d by [sqlite3_me
1f1a0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 mory_used()] and
1f1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
1f1c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1f1d0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 include any ove
1f1e0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 rhead.** added b
1f1f0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 y SQLite in its
1f200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1f210 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1f220 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 c()],.** but not
1f230 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 overhead added
1f240 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 by the any under
1f250 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 lying system lib
1f260 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 rary.** routines
1f270 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d that [sqlite3_m
1f280 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c alloc()] may cal
1f290 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 l..**.** ^The me
1f2a0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 mory high-water
1f2b0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f mark is reset to
1f2c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
1f2d0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 ue of.** [sqlite
1f2e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1f2f0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 if and only if
1f300 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f the parameter to
1f310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
1f320 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1f330 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 is true. ^The
1f340 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
1f350 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 * by [sqlite3_me
1f360 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 mory_highwater(1
1f370 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 )] is the high-w
1f380 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 ater mark.** pri
1f390 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e or to the reset.
1f3a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 .*/.SQLITE_API s
1f3b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
1f3c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1f3d0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
1f3e0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
1f3f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
1f400 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
1f410 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
1f420 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 CAPI3REF: Pseud
1f430 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 o-Random Number
1f440 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 Generator.**.**
1f450 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 SQLite contains
1f460 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 a high-quality p
1f470 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d seudo-random num
1f480 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 ber generator (P
1f490 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 RNG) used to.**
1f4a0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 select random [R
1f4b0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 OWID | ROWIDs] w
1f4c0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 hen inserting ne
1f4d0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 w records into a
1f4e0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 table that.** a
1f4f0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 lready uses the
1f500 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 largest possible
1f510 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 [ROWID]. The P
1f520 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
1f530 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
1f540 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
1f550 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
1f560 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
1f570 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
1f580 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
1f590 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
1f5a0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
1f5b0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
1f5c0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 .**.** ^A call t
1f5d0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 o this routine s
1f5e0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 tores N bytes of
1f5f0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
1f600 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
1f610 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
1f620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
1f630 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 invoked (either
1f640 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 internally or b
1f650 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 y.** the applica
1f660 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 tion) the PRNG i
1f670 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 s seeded using r
1f680 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
1f690 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 ed.** from the x
1f6a0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
1f6b0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 d of the default
1f6c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1f6d0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c bject..** ^On al
1f6e0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 l subsequent inv
1f6f0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 ocations, the ps
1f700 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
1f710 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
1f720 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
1f730 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
1f740 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
1f750 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
1f760 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 .** method..*/.S
1f770 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
1f780 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
1f790 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
1f7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f7b0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
1f7c0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
1f7d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
1f7e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
1f7f0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 isters an author
1f800 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
1f810 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
1f820 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1f830 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
1f840 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
1f850 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
1f860 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1f870 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1f880 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
1f890 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
1f8a0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
1f8b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1f8c0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
1f8d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f8e0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
1f8f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1f900 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
1f910 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
1f920 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 ^At various.** p
1f930 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
1f940 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
1f950 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
1f960 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
1f970 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
1f980 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
1f990 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1f9a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1f9b0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
1f9c0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
1f9d0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 allowed. ^The
1f9e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1f9f0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
1fa00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
1fa10 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
1fa20 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
1fa30 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
1fa40 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
1fa50 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
1fa60 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
1fa70 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
1fa80 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
1fa90 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
1faa0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
1fab0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
1fac0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
1fad0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
1fae0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 error. ^If the
1faf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1fb00 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1fb10 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
1fb20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e than [SQLITE_IGN
1fb30 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b ORE], [SQLITE_OK
1fb40 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 ], or [SQLITE_DE
1fb50 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 NY].** then the
1fb60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1fb70 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
1fb80 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
1fb90 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 riggered.** the
1fba0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
1fbb0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
1fbc0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
1fbd0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
1fbe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1fbf0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 ITE_OK], that me
1fc00 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f ans the operatio
1fc10 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 n.** requested i
1fc20 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 s ok. ^When the
1fc30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1fc40 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
1fc50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1fc60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1fc70 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
1fc80 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
1fc90 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1fca0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
1fcb0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
1fcc0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
1fcd0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
1fce0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e denied. .**.** ^
1fcf0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1fd00 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1fd10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1fd20 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
1fd30 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
1fd40 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
1fd50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1fd60 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 () interface. ^T
1fd70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1fd80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
1fd90 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
1fda0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
1fdb0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
1fdc0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
1fdd0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
1fde0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
1fdf0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 uthorized. ^The
1fe00 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
1fe10 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
1fe20 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
1fe30 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 k are zero-termi
1fe40 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
1fe50 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
1fe60 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 ional.** details
1fe70 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
1fe80 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
1fe90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
1fea0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
1feb0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a [SQLITE_READ].*
1fec0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 * and the callba
1fed0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
1fee0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
1fef0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1ff00 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 statement] stat
1ff10 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 ement is constru
1ff20 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 cted to substitu
1ff30 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c te.** a NULL val
1ff40 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 ue in place of t
1ff50 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
1ff60 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a that would have.
1ff70 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 ** been read if
1ff80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 [SQLITE_OK] had
1ff90 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 been returned.
1ffa0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f The [SQLITE_IGNO
1ffb0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 RE].** return ca
1ffc0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e n be used to den
1ffd0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 y an untrusted u
1ffe0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e ser access to in
1fff0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 dividual.** colu
20000 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a mns of a table..
20010 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
20020 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
20030 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 E_DELETE] and th
20040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
20050 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 ns.** [SQLITE_IG
20060 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b NORE] then the [
20070 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f DELETE] operatio
20080 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 n proceeds but t
20090 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 he.** [truncate
200a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 optimization] is
200b0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c disabled and al
200c0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 l rows are delet
200d0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e ed individually.
200e0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 .**.** An author
200f0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 izer is used whe
20100 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
20110 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a re | preparing].
20120 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
20130 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
20140 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 ted source, to e
20150 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 nsure that the S
20160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
20170 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
20180 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 ccess data they
20190 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
201a0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
201b0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 they do not.** t
201c0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 ry to execute ma
201d0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
201e0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
201f0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
20200 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
20210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
20220 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
20230 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
20240 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
20250 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
20260 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
20270 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
20280 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
20290 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
202a0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
202b0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
202c0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
202d0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
202e0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
202f0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
20300 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
20310 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
20320 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f being [sqlite3_
20330 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
20340 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 ed] that.** disa
20350 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 llows everything
20360 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d except [SELECT]
20370 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
20380 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
20390 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f that need to pro
203a0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e cess SQL from un
203b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a trusted sources.
203c0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f ** might also co
203d0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 nsider lowering
203e0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 resource limits
203f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
20400 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c imit()].** and l
20410 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 imiting database
20420 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 size using the
20430 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
20440 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 [PRAGMA].** in
20450 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e addition to usin
20460 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e g an authorizer.
20470 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 .**.** ^(Only a
20480 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
20490 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
204a0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
204b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
204c0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
204d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
204e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
204f0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
20500 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 revious call.)^
20510 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 ^Disable the au
20520 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
20530 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
20540 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
20550 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
20560 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
20570 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 ..**.** The auth
20580 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
20590 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
205a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
205b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
205c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
205d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
205e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
205f0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 lback..** Note t
20600 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
20610 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
20620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
20630 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
20640 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
20650 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
20660 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
20670 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
20680 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e ragraph..**.** ^
20690 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
206a0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
206b0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
206c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
206d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
206e0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
206f0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
20700 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
20710 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
20720 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
20730 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
20740 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
20750 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
20760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
20770 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
20780 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
20790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
207a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
207b0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 at the authorize
207c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
207d0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e voked only durin
207e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 g.** [sqlite3_pr
207f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
20800 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
20810 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
20820 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
20830 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
20840 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
20850 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e ite3_step()], un
20860 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 less.** as state
20870 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 d in the previou
20880 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c s paragraph, sql
20890 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f ite3_step() invo
208a0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 kes.** sqlite3_p
208b0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 repare_v2() to r
208c0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 eprepare a state
208d0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 ment after a sch
208e0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 ema change..*/.S
208f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
20900 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
20910 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
20920 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
20930 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
20940 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
20950 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
20960 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
20970 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
20980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20990 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
209a0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a turn Codes.**.**
209b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
209c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
209d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
209e0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
209f0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
20a00 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
20a10 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
20a20 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
20a30 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
20a40 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
20a50 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
20a60 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
20a70 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
20a80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
20a90 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
20aa0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
20ab0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
20ac0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
20ad0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
20ae0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 SQLITE_IGNORE i
20af0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 s also used as a
20b00 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 [SQLITE_ROLLBAC
20b10 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d K | return code]
20b20 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 .** from the [sq
20b30 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f lite3_vtab_on_co
20b40 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 nflict()] interf
20b50 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
20b60 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
20b70 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
20b80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
20b90 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
20ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
20bb0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
20bc0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
20bd0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
20be0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
20bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
20c00 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
20c10 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
20c20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
20c30 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
20c40 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
20c50 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
20c60 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
20c70 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
20c80 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
20c90 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
20ca0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
20cb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
20cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
20cd0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
20ce0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
20cf0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
20d00 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
20d10 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
20d20 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
20d30 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
20d40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20d50 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
20d60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
20d70 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
20d80 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
20d90 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
20da0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
20db0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
20dc0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
20dd0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
20de0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
20df0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20e00 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
20e10 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
20e20 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
20e30 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
20e40 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
20e50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
20e60 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 . ^(The 5th par
20e70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
20e80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20e90 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
20ea0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
20eb0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
20ec0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
20ed0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 plicable.)^ ^Th
20ee0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
20ef0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
20f00 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
20f10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
20f20 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
20f30 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
20f40 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
20f50 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
20f60 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
20f70 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
20f80 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
20f90 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
20fa0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
20fb0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
20fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
20fe0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
20ff0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
21000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21010 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
21020 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
21030 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
21040 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
21050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21060 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
21070 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
21080 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
210a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
210b0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
210c0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
210d0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
210e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
210f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21100 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
21110 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
21120 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
21130 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
21140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
21150 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
21160 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
21170 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
21180 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
21190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
211a0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
211b0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
211c0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
211d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
211e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
211f0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
21200 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
21210 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
21220 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
21230 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
21240 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
21250 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
21260 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
21270 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21280 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
21290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
212a0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
212b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
212c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
212d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
212e0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
212f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
21300 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
21310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21320 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
21330 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
21340 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
21350 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21370 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
21380 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
21390 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
213a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
213b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
213c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
213d0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
213e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
213f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
21400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21410 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
21420 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
21430 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
21440 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
21450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21460 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
21470 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
21480 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
21490 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
214a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
214b0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
214c0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
214d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
214e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
214f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21500 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
21510 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
21520 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
21530 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
21540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21550 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
21560 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
21570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21580 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
215a0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
215b0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
215c0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
215d0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
215e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
215f0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
21600 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
21610 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
21620 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
21630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
21640 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
21650 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
21660 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
21670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
21690 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
216a0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
216b0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
216c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
216d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
216e0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
216f0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
21700 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
21710 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
21720 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
21730 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
21740 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
21750 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
21760 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21770 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
21780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
21790 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
217a0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
217b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
217c0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
217d0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
217e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
217f0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
21800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21810 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
21820 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
21830 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
21840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21860 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
21870 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
21880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
21890 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
218a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
218b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
218c0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
218d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
218e0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
218f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21900 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
21910 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
21920 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
21930 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
21940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21950 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
21960 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
21970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21980 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
21990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
219a0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
219b0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
219c0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
219d0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
219e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
219f0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
21a00 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
21a10 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
21a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21a30 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 : Tracing And Pr
21a40 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e ofiling Function
21a50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
21a60 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 utines register
21a70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
21a80 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 ns that can be u
21a90 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 sed for.** traci
21aa0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 ng and profiling
21ab0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
21ac0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 f SQL statements
21ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c ..**.** ^The cal
21ae0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
21af0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
21b00 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 ite3_trace() is
21b10 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 invoked at.** va
21b20 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e rious times when
21b30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
21b40 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 t is being run b
21b50 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 y [sqlite3_step(
21b60 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 )]..** ^The sqli
21b70 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c te3_trace() call
21b80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
21b90 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e with a UTF-8 ren
21ba0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a dering of the.**
21bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
21bc0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 ext as the state
21bd0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e ment first begin
21be0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 s executing..**
21bf0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c ^(Additional sql
21c00 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
21c10 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 lbacks might occ
21c20 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 ur.** as each tr
21c30 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 iggered subprogr
21c40 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 am is entered.
21c50 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f The callbacks fo
21c60 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f r triggers.** co
21c70 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 ntain a UTF-8 SQ
21c80 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 L comment that i
21c90 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 dentifies the tr
21ca0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e igger.)^.**.** ^
21cb0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
21cc0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
21cd0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 by sqlite3_prof
21ce0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ile() is invoked
21cf0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 .** as each SQL
21d00 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 statement finish
21d10 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c es. ^The profil
21d20 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
21d30 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 ins.** the origi
21d40 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 nal statement te
21d50 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 xt and an estima
21d60 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b te of wall-clock
21d70 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 time.** of how
21d80 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d long that statem
21d90 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e ent took to run.
21da0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 ^The profile c
21db0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 allback.** time
21dc0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e is in units of n
21dd0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 anoseconds, howe
21de0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 ver the current
21df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
21e00 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c * is only capabl
21e10 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 e of millisecond
21e20 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 resolution so t
21e30 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 he six least sig
21e40 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 nificant.** digi
21e50 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 ts in the time a
21e60 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 re meaningless.
21e70 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
21e80 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 of SQLite.** mi
21e90 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 ght provide grea
21ea0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f ter resolution o
21eb0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 n the profiler c
21ec0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a allback. The.**
21ed0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
21ee0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
21ef0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 onsidered experi
21f00 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a mental and is.**
21f10 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
21f20 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 ge in future ver
21f30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
21f40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
21f50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 oid *sqlite3_tra
21f60 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 ce(sqlite3*, voi
21f70 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a d(*xTrace)(void*
21f80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 ,const char*), v
21f90 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 oid*);.SQLITE_AP
21fa0 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d I SQLITE_EXPERIM
21fb0 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 ENTAL void *sqli
21fc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 te3_profile(sqli
21fd0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 te3*,. void(*x
21fe0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 Profile)(void*,c
21ff0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
22000 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 e3_uint64), void
22010 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
22020 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
22030 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
22040 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
22050 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
22060 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 r(D,N,X,P) inter
22070 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 face causes the
22080 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 callback.** func
22090 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 tion X to be inv
220a0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c oked periodicall
220b0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 y during long ru
220c0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a nning calls to.*
220d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * [sqlite3_exec(
220e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
220f0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 p()] and [sqlite
22100 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 3_get_table()] f
22110 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 or.** database c
22120 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e onnection D. An
22130 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 example use for
22140 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 this.** interfa
22150 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 ce is to keep a
22160 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 GUI updated duri
22170 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 ng a large query
22180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 ..**.** ^The par
22190 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 ameter P is pass
221a0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
221b0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
221c0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c to the .** call
221d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e back function X.
221e0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 ^The parameter
221f0 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 N is the number
22200 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c of .** [virtual
22210 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 machine instruc
22220 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 tions] that are
22230 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 evaluated betwee
22240 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 n successive.**
22250 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
22260 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a he callback X..*
22270 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e *.** ^Only a sin
22280 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e gle progress han
22290 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 dler may be defi
222a0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 ned at one time
222b0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 per.** [database
222c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 connection]; se
222d0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 tting a new prog
222e0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e ress handler can
222f0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 cels the.** old
22300 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 one. ^Setting p
22310 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 arameter X to NU
22320 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 LL disables the
22330 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
22340 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 ..** ^The progre
22350 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c ss handler is al
22360 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 so disabled by s
22370 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 etting N to a va
22380 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e lue less.** than
22390 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 1..**.** ^If th
223a0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
223b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
223c0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
223d0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
223e0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
223f0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
22400 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
22410 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
22420 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
22430 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
22440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
22450 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c ess handler call
22460 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
22470 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
22480 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
22490 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
224a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
224b0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 ed the progress
224c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 handler..** Note
224d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
224e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
224f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
22500 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
22510 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
22520 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
22530 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
22540 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
22550 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f paragraph..**.*/
22560 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
22570 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
22580 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
22590 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
225a0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
225b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
225c0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
225d0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
225e0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 on.**.** ^These
225f0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
22600 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
22610 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 file as specifi
22620 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 ed by the .** fi
22630 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e lename argument.
22640 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 ^The filename a
22650 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 rgument is inter
22660 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 preted as UTF-8
22670 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
22680 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
22690 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 3_open_v2() and
226a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 as UTF-16 in the
226b0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 native byte.**
226c0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 order for sqlite
226d0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 3_open16(). ^(A
226e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
226f0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 tion] handle is
22700 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 usually.** retur
22710 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 ned in *ppDb, ev
22720 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f en if an error o
22730 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
22740 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 exception is th
22750 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 at.** if SQLite
22760 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
22770 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
22780 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 hold the [sqlite
22790 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 3] object,.** a
227a0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 NULL will be wri
227b0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 tten into *ppDb
227c0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 instead of a poi
227d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
227e0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e ite3].** object.
227f0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 )^ ^(If the data
22800 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
22810 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
22820 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
22830 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
22840 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
22850 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
22860 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
22870 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a urned.)^ ^The.**
22880 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
22890 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
228a0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 errmsg16()] rout
228b0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 ines can be used
228c0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e to obtain.** an
228d0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 English languag
228e0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 e description of
228f0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f the error follo
22900 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f wing a failure o
22910 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 f any.** of the
22920 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 sqlite3_open() r
22930 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
22940 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
22950 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
22960 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
22970 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
22980 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
22990 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
229a0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
229b0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
229c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
229d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
229e0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
229f0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
22a00 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
22a10 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
22a20 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
22a30 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
22a40 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
22a50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
22a60 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
22a70 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
22a80 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
22a90 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
22aa0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
22ab0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
22ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
22ad0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
22ae0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
22af0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
22b00 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
22b10 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
22b20 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
22b30 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
22b40 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
22b50 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
22b60 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
22b70 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
22b80 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
22b90 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
22ba0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
22bb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
22bc0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
22bd0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
22be0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
22bf0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
22c00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
22c10 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
22c20 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
22c30 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
22c40 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
22c50 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
22c60 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
22c70 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
22c80 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
22c90 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
22ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
22cb0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
22cc0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
22cd0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
22ce0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
22cf0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
22d00 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
22d10 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
22d20 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
22d30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
22d40 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
22d50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
22d60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
22d70 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
22d80 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
22d90 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
22da0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
22db0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
22dc0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
22dd0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
22de0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
22df0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
22e00 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
22e10 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
22e20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
22e30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
22e40 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
22e50 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
22e60 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
22e70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
22e80 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
22e90 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
22ea0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
22eb0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
22ec0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
22ed0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
22ee0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
22ef0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
22f00 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
22f10 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
22f20 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
22f30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
22f40 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
22f50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
22f60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
22f70 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
22f80 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
22f90 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
22fa0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
22fb0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
22fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
22fd0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
22fe0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
22ff0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
23000 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
23010 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
23020 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
23030 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
23040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
23050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
23060 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
23070 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
23080 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
23090 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
230a0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
230b0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
230c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
230d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
230e0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
230f0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
23100 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
23110 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
23120 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
23130 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
23140 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
23150 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
23160 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
23170 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
23180 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
23190 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
231a0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
231b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
231c0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
231d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
231e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
231f0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
23200 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
23210 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
23220 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
23230 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
23240 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
23250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
23260 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
23270 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
23280 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
23290 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
232a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
232b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
232c0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
232d0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
232e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
232f0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
23300 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
23310 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
23320 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
23330 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
23340 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
23350 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
23360 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
23370 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
23380 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
23390 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
233a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
233b0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
233c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
233d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
233e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
233f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
23400 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
23410 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
23420 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
23430 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
23440 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
23450 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
23460 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
23470 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
23480 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
23490 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
234a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
234b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
234c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
234d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
234e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
234f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
23500 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
23510 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
23520 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
23530 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
23540 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
23550 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
23560 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
23570 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
23580 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
23590 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
235a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
235b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
235c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
235d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
235e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
235f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
23600 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
23610 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
23620 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
23630 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
23640 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
23650 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
23660 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
23670 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
23680 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
23690 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
236a0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
236b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
236c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
236d0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
236e0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
236f0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
23700 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
23710 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
23720 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
23730 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
23740 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
23750 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
23760 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
23770 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
23780 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
23790 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
237a0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
237b0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
237c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
237d0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
237e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
237f0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
23800 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
23810 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
23820 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
23830 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
23840 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
23850 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
23860 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
23870 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
23880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
23890 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
238a0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
238b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
238c0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
238d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
238e0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
238f0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
23900 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
23910 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
23920 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
23930 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
23940 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
23950 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
23960 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
23970 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
23980 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
23990 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
239a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
239b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
239c0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
239d0 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
239e0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
239f0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
23a00 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
23a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
23a20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
23a30 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
23a40 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
23a50 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
23a60 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
23a70 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
23a80 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
23a90 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
23aa0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
23ab0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
23ac0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
23ad0 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
23ae0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
23af0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
23b00 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
23b10 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
23b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
23b30 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
23b40 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
23b50 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
23b60 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
23b70 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
23b80 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
23b90 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
23ba0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
23bb0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
23bc0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
23bd0 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
23be0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
23bf0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
23c00 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
23c10 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
23c20 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
23c30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
23c40 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
23c50 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 ** ^On windows,
23c60 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e the first compon
23c70 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 ent of an absolu
23c80 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 te path .** is a
23c90 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 drive specifica
23ca0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 tion (e.g. "C:")
23cb0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 ..**.** [[core U
23cc0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 RI query paramet
23cd0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 ers]].** The que
23ce0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
23cf0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 a URI may contai
23d00 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 n parameters tha
23d10 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 t are interprete
23d20 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 d.** either by S
23d30 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 QLite itself, or
23d40 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 by a [VFS | cus
23d50 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e tom VFS implemen
23d60 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 tation]..** SQLi
23d70 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
23d80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
23d90 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
23da0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a rs:.**.** <ul>.*
23db0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c * <li> <b>vfs<
23dc0 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 /b>: ^The "vfs"
23dd0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
23de0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 used to specify
23df0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 the name of.**
23e00 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 a VFS object
23e10 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 that provides t
23e20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
23e30 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
23e40 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 at should.**
23e50 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 be used to acce
23e60 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
23e70 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 file on disk. ^I
23e80 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 f this option is
23e90 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 set to.** a
23ea0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 n empty string t
23eb0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f he default VFS o
23ec0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e bject is used. ^
23ed0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e Specifying an un
23ee0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 known.** VFS
23ef0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 is an error. ^I
23f00 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
23f10 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
23f20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 the vfs option i
23f30 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 s.** present
23f40 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 , then the VFS s
23f50 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
23f60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 option takes pre
23f70 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 cedence over.**
23f80 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 the value pa
23f90 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
23fa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
23fb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
23fc0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
23fd0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 <b>mode</b>: ^(T
23fe0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
23ff0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
24000 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 either "ro", "rw
24010 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 " or.** "rwc
24020 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f ". Attempting to
24030 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f set it to any o
24040 74 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e ther value is an
24050 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 error)^. .**
24060 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 ^If "ro" is sp
24070 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 ecified, then th
24080 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
24090 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e ened for read-on
240a0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 ly .** acces
240b0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 s, just as if th
240c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
240d0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 EADONLY] flag ha
240e0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 d been set in th
240f0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 e .** third
24100 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
24110 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
24120 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f . ^If the mode o
24130 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 ption is set to
24140 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 .** "rw", th
24150 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
24160 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
24170 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f ad-write (but no
24180 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 t create) .**
24190 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 access, as if
241a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
241b0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 WRITE (but not S
241c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
241d0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 E) had .** b
241e0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 een set. ^Value
241f0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c "rwc" is equival
24200 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 ent to setting b
24210 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 oth .** SQLI
24220 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
24230 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 E and SQLITE_OPE
24240 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71 N_CREATE. ^If sq
24250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
24260 69 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c is .** used,
24270 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 it is an error
24280 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c to specify a val
24290 75 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 ue for the mode
242a0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
242b0 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 s .** less r
242c0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 estrictive than
242d0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 that specified b
242e0 79 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 y the flags pass
242f0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 ed as the third
24300 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 .** paramete
24310 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 r..**.** <li>
24320 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 <b>cache</b>: ^T
24330 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
24340 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
24350 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 either "shared"
24360 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 or.** "priv
24370 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 ate". ^Setting i
24380 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 t to "shared" is
24390 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
243a0 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 etting the.**
243b0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 SQLITE_OPEN_SH
243c0 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e AREDCACHE bit in
243d0 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
243e0 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a ent passed to.**
243f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 sqlite3_ope
24400 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 n_v2(). ^Setting
24410 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d the cache param
24420 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 eter to "private
24430 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 " is .** equ
24440 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
24450 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 ng the SQLITE_OP
24460 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
24470 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 bit..** ^If
24480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24490 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
244a0 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 e "cache" parame
244b0 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 ter is present i
244c0 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 n.** a URI f
244d0 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c ilename, its val
244e0 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 ue overrides any
244f0 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 behaviour reque
24500 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a sted by setting.
24510 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
24520 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
24530 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 or SQLITE_OPEN_S
24540 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e HAREDCACHE flag.
24550 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
24560 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
24570 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 nknown parameter
24580 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f in the query co
24590 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
245a0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 is not an.** er
245b0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 ror. Future ver
245c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
245d0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 might understand
245e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 additional quer
245f0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e y.** parameters.
24600 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 See "[query pa
24610 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 rameters with sp
24620 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f ecial meaning to
24630 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a SQLite]" for.**
24640 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
24650 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b rmation..**.** [
24660 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 [URI filename ex
24670 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 amples]] <h3>URI
24680 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
24690 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 es</h3>.**.** <t
246a0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 able border="1"
246b0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c align=center cel
246c0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c lpadding=5>.** <
246d0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 tr><th> URI file
246e0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c names <th> Resul
246f0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 ts.** <tr><td> f
24700 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e ile:data.db <td>
24710 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
24720 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
24730 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
24740 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a rent directory..
24750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
24760 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
24770 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 .db<br>.**
24780 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 file:///home
24790 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 /fred/data.db <b
247a0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 r> .**
247b0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 file://localhost
247c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
247d0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a db <br> <td> .**
247e0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
247f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
24800 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
24810 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 a.db"..** <tr><t
24820 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 d> file://darkst
24830 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ar/home/fred/dat
24840 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
24850 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
24860 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e "darkstar" is n
24870 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 ot a recognized
24880 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 authority..** <t
24890 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 r><td style="whi
248a0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 te-space:nowrap"
248b0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 > .** f
248c0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 ile:///C:/Docume
248d0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 nts%20and%20Sett
248e0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f ings/fred/Deskto
248f0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 p/data.db.**
24900 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e <td> Windows on
24910 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c ly: Open the fil
24920 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 e "data.db" on f
24930 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e red's desktop on
24940 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 drive.**
24950 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 C:. Note that
24960 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e the %20 escapin
24970 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c g in this exampl
24980 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c e is not strictl
24990 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e y .** n
249a0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 ecessary - space
249b0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 characters can
249c0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c be used literall
249d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e y.** in
249e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a URI filenames..
249f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
24a00 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f :data.db?mode=ro
24a10 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c &cache=private <
24a20 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
24a30 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 Open file "data
24a40 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 .db" in the curr
24a50 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f ent directory fo
24a60 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 r read-only acce
24a70 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ss..**
24a80 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
24a90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
24aa0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 red-cache mode i
24ab0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 s enabled by.**
24ac0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
24ad0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 , use a private
24ae0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cache..** <tr><t
24af0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
24b00 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 ed/data.db?vfs=u
24b10 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a nix-nolock <td>.
24b20 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
24b30 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
24b40 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 d/data.db". Use
24b50 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 the special VFS
24b60 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a "unix-nolock"..*
24b70 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
24b80 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 data.db?mode=rea
24b90 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 donly <td> .**
24ba0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 An error
24bb0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 . "readonly" is
24bc0 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 not a valid opti
24bd0 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 on for the "mode
24be0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 " parameter..**
24bf0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e </table>.**.** ^
24c00 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 URI hexadecimal
24c10 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 escape sequences
24c20 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f (%HH) are suppo
24c30 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 rted within the
24c40 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 path and.** quer
24c50 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 y components of
24c60 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 a URI. A hexadec
24c70 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
24c80 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 ence consists of
24c90 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 a.** percent si
24ca0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f gn - "%" - follo
24cb0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 wed by exactly t
24cc0 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 wo hexadecimal d
24cd0 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 igits .** specif
24ce0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 ying an octet va
24cf0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 lue. ^Before the
24d00 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 path or query c
24d10 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a omponents of a.*
24d20 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 * URI filename a
24d30 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 re interpreted,
24d40 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 they are encoded
24d50 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 using UTF-8 and
24d60 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 all .** hexadec
24d70 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
24d80 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 ences replaced b
24d90 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 y a single byte
24da0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a containing the.*
24db0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 * corresponding
24dc0 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 octet. If this p
24dd0 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 rocess generates
24de0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d an invalid UTF-
24df0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 8 encoding,.** t
24e00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
24e10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
24e20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
24e30 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 ws users:</b> T
24e40 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 he encoding used
24e50 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d for the filenam
24e60 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 e argument.** of
24e70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
24e80 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
24e90 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 _v2() must be UT
24ea0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 F-8, not whateve
24eb0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 r.** codepage is
24ec0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
24ed0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 ed. Filenames c
24ee0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e ontaining intern
24ef0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 ational.** chara
24f00 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f cters must be co
24f10 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 nverted to UTF-8
24f20 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e prior to passin
24f30 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 g them into.** s
24f40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
24f50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
24f60 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ()..*/.SQLITE_AP
24f70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
24f80 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 en(. const char
24f90 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
24fa0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
24fb0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
24fc0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
24fd0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
24fe0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
24ff0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
25000 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
25010 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
25020 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
25030 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
25040 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
25050 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
25060 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
25070 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
25080 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 dle */.);.SQLITE
25090 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
250a0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
250b0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
250c0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
250d0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
250e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
250f0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
25100 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
25110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
25120 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
25130 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
25140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
25150 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
25160 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
25170 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
25180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
25190 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
251a0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
251b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
251c0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
251d0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
251e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
251f0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
25200 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
25210 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
25220 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
25230 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
25240 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
25250 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
25260 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
25270 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
25280 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
25290 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
252a0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
252b0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
252c0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
252d0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
252e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
252f0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
25300 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
25310 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
25320 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
25330 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
25340 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
25350 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
25360 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
25370 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
25380 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
25390 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
253a0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
253b0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
253c0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
253d0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
253e0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
253f0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
25400 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
25410 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
25420 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
25430 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
25440 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
25450 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
25460 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
25470 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
25480 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
25490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
254a0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
254b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
254c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
254d0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
254e0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
254f0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
25500 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
25510 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
25520 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
25530 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
25540 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
25550 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
25560 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
25570 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
25580 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
25590 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
255a0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
255b0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
255c0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
255d0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
255e0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
255f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
25600 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
25610 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
25620 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
25630 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
25640 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
25650 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
25660 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
25670 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
25680 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
25690 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
256a0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
256b0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
256c0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
256d0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
256e0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
256f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
25700 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
25710 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
25720 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
25730 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
25740 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
25750 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
25760 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
25770 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
25780 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
25790 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
257a0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
257b0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
257c0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
257d0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
257e0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
257f0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
25800 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
25810 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
25820 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
25830 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
25840 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
25850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
25860 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
25870 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
25880 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
25890 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
258a0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
258b0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
258c0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
258d0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
258e0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
258f0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
25900 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
25910 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
25920 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
25930 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
25940 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
25950 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
25960 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
25970 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
25980 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
25990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
259a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
259b0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a er(const char *z
259c0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 Filename, const
259d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 char *zParam);.S
259e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
259f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
25a00 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
25a10 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
25a20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
25a30 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 fault);.SQLITE_A
25a40 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
25a50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
25a60 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 64(const char*,
25a70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
25a80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f ite3_int64);.../
25a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
25aa0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d rror Codes And M
25ab0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 essages.**.** ^T
25ac0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f he sqlite3_errco
25ad0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 de() interface r
25ae0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
25af0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
25b00 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
25b10 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
25b20 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e r the most recen
25b30 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 t failed sqlite3
25b40 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 _* API call.** a
25b50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
25b60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
25b70 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 ction]. If a pri
25b80 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c or API call fail
25b90 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f ed.** but the mo
25ba0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 st recent API ca
25bb0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 ll succeeded, th
25bc0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
25bd0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 rom.** sqlite3_e
25be0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 rrcode() is unde
25bf0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c fined. ^The sql
25c00 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 ite3_extended_er
25c10 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 rcode().** inter
25c20 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 face is the same
25c30 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
25c40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 always returns t
25c50 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 he .** [extended
25c60 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 result code] ev
25c70 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 en when extended
25c80 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
25c90 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a e.** disabled..*
25ca0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
25cb0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
25cc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
25cd0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
25ce0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
25cf0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
25d00 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
25d10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
25d20 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
25d30 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 ly..** ^(Memory
25d40 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f to hold the erro
25d50 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
25d60 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 is managed inte
25d70 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 rnally..** The a
25d80 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 pplication does
25d90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 not need to worr
25da0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 y about freeing
25db0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 the result..** H
25dc0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f owever, the erro
25dd0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 r string might b
25de0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 e overwritten or
25df0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a deallocated by.
25e00 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ** subsequent ca
25e10 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c lls to other SQL
25e20 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 ite interface fu
25e30 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a nctions.)^.**.**
25e40 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c When the serial
25e50 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
25e60 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c mode] is in use,
25e70 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 it might be the
25e80 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 .** case that a
25e90 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 second error occ
25ea0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 urs on a separat
25eb0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 e thread in betw
25ec0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 een.** the time
25ed0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 of the first err
25ee0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 or and the call
25ef0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
25f00 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 ces..** When tha
25f10 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 t happens, the s
25f20 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c econd error will
25f30 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e be reported sin
25f40 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 ce these.** inte
25f50 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 rfaces always re
25f60 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 port the most re
25f70 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f cent result. To
25f80 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 avoid.** this,
25f90 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 each thread can
25fa0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 obtain exclusive
25fb0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 use of the [dat
25fc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25fd0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 ] D.** by invoki
25fe0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
25ff0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 x_enter]([sqlite
26000 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
26010 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 before beginning
26020 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 .** to use D and
26030 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
26040 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 e3_mutex_leave](
26050 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
26060 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 x](D)) after.**
26070 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 all calls to the
26080 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 interfaces list
26090 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 ed here are comp
260a0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 leted..**.** If
260b0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 an interface fai
260c0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d ls with SQLITE_M
260d0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e ISUSE, that mean
260e0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a s the interface.
260f0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 ** was invoked i
26100 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 ncorrectly by th
26110 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
26120 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 In that case, th
26130 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 e.** error code
26140 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 and message may
26150 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 or may not be se
26160 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
26170 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 int sqlite3_err
26180 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
26190 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
261a0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
261b0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 ed_errcode(sqlit
261c0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f e3 *db);.SQLITE_
261d0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
261e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 sqlite3_errmsg(s
261f0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 qlite3*);.SQLITE
26200 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
26210 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 *sqlite3_errmsg1
26220 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 6(sqlite3*);../*
26230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
26240 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 L Statement Obje
26250 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
26260 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d {prepared statem
26270 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 ent} {prepared s
26280 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a tatements}.**.**
26290 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
262a0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 this object repr
262b0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 esents a single
262c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
262d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
262e0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e variously known
262f0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 as a "prepared
26300 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a statement" or a.
26310 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c ** "compiled SQL
26320 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 statement" or s
26330 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 imply as a "stat
26340 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ement"..**.** Th
26350 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 e life of a stat
26360 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 ement object goe
26370 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 s something like
26380 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
26390 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
263a0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
263b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
263c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 re_v2()] or a re
263d0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 lated.** fu
263e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 nction..** <li>
263f0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b Bind values to [
26400 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d host parameters]
26410 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
26420 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 e3_bind_*().**
26430 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a interfaces..
26440 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 ** <li> Run the
26450 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b SQL by calling [
26460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
26470 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
26480 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 s..** <li> Reset
26490 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 the statement u
264a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
264b0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
264c0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
264d0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
264e0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
264f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
26500 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
26510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
26520 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
26530 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 ol>.**.** Refer
26540 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e to documentation
26550 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d on individual m
26560 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 ethods above for
26570 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
26580 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 nformation..*/.t
26590 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
265a0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 lite3_stmt sqlit
265b0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 e3_stmt;../*.**
265c0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 CAPI3REF: Run-ti
265d0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 me Limits.**.**
265e0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^(This interface
265f0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 allows the size
26600 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 of various cons
26610 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d tructs to be lim
26620 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e ited.** on a con
26630 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 nection by conne
26640 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 ction basis. Th
26650 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
26660 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 r is the.** [dat
26670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
26680 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 ] whose limit is
26690 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 to be set or qu
266a0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 eried. The.** s
266b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
266c0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c is one of the [l
266d0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d imit categories]
266e0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a that define a.*
266f0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 * class of const
26700 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 ructs to be size
26710 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 limited. The t
26720 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
26730 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d s the.** new lim
26740 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 it for that cons
26750 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e truct.)^.**.** ^
26760 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 If the new limit
26770 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e is a negative n
26780 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 umber, the limit
26790 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a is unchanged..*
267a0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d * ^(For each lim
267b0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 it category SQLI
267c0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 TE_LIMIT_<i>NAME
267d0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 </i> there is a
267e0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 .** [limits | ha
267f0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a rd upper bound].
26800 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c ** set at compil
26810 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 e-time by a C pr
26820 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
26830 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 called.** [limi
26840 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f ts | SQLITE_MAX_
26850 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a <i>NAME</i>]..**
26860 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 (The "_LIMIT_"
26870 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 in the name is c
26880 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f hanged to "_MAX_
26890 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 ".))^.** ^Attemp
268a0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 ts to increase a
268b0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 limit above its
268c0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
268d0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c d are.** silentl
268e0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 y truncated to t
268f0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f he hard upper bo
26900 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 und..**.** ^Rega
26910 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
26920 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d r or not the lim
26930 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 it was changed,
26940 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the .** [sqlite3
26950 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 _limit()] interf
26960 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
26970 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 prior value of t
26980 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 he limit..** ^He
26990 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 nce, to find the
269a0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f current value o
269b0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 f a limit withou
269c0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a t changing it,.*
269d0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 * simply invoke
269e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 this interface w
269f0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 ith the third pa
26a00 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d rameter set to -
26a10 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 1..**.** Run-tim
26a20 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 e limits are int
26a30 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
26a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 applications th
26a50 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 at manage.** bot
26a60 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 h their own inte
26a70 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e rnal database an
26a80 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 d also databases
26a90 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f that are contro
26aa0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 lled.** by untru
26ab0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f sted external so
26ac0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 urces. An examp
26ad0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d le application m
26ae0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 ight be a.** web
26af0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 browser that ha
26b00 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 s its own databa
26b10 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ses for storing
26b20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 history and.** s
26b30 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 eparate database
26b40 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 s controlled by
26b50 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 JavaScript appli
26b60 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 cations download
26b70 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e ed.** off the In
26b80 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 ternet. The int
26b90 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 ernal databases
26ba0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 can be given the
26bb0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 .** large, defau
26bc0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 lt limits. Data
26bd0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 bases managed by
26be0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
26bf0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 s can.** be give
26c00 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c n much smaller l
26c10 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 imits designed t
26c20 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 o prevent a deni
26c30 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a al of service.**
26c40 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f attack. Develo
26c50 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 pers might also
26c60 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 want to use the
26c70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
26c80 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e horizer()].** in
26c90 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 terface to furth
26ca0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 er control untru
26cb0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 sted SQL. The s
26cc0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ize of the datab
26cd0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 ase.** created b
26ce0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 y an untrusted s
26cf0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e cript can be con
26d00 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 tained using the
26d10 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f .** [max_page_co
26d20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a unt] [PRAGMA]..*
26d30 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d *.** New run-tim
26d40 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 e limit categori
26d50 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 es may be added
26d60 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
26d70 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 es..*/.SQLITE_AP
26d80 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 I int sqlite3_li
26d90 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e mit(sqlite3*, in
26da0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c t id, int newVal
26db0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26dc0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d EF: Run-Time Lim
26dd0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a it Categories.**
26de0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 KEYWORDS: {limi
26df0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 t category} {*li
26e00 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a mit categories}.
26e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
26e20 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 tants define var
26e30 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 ious performance
26e40 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 limits.** that
26e50 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 can be lowered a
26e60 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 t run-time using
26e70 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
26e80 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 )]..** The synop
26e90 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 sis of the meani
26ea0 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f ngs of the vario
26eb0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f us limits is sho
26ec0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 wn below..** Add
26ed0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
26ee0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ion is available
26ef0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 at [limits | Li
26f00 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e mits in SQLite].
26f10 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
26f20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
26f30 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c NGTH]] ^(<dt>SQL
26f40 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
26f50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26f60 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
26f70 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 any string or B
26f80 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 LOB or table row
26f90 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 , in bytes.<dd>)
26fa0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26fb0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
26fc0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
26fd0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
26fe0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
26ff0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
27000 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 of an SQL state
27010 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c ment, in bytes.<
27020 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
27030 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
27040 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 MN]] ^(<dt>SQLIT
27050 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f E_LIMIT_COLUMN</
27060 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
27070 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
27080 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 columns in a ta
27090 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f ble definition o
270a0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 r in the.** resu
270b0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
270c0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 ECT] or the maxi
270d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
270e0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 lumns in an inde
270f0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 x.** or in an OR
27100 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 DER BY or GROUP
27110 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 BY clause.</dd>)
27120 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
27130 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
27140 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
27150 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 _LIMIT_EXPR_DEPT
27160 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
27170 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
27180 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 of the parse tre
27190 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 e on any express
271a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ion.</dd>)^.**.*
271b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
271c0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
271d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
271e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
271f0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ELECT</dt>.** <d
27200 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
27210 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
27220 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 a compound SELE
27230 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 CT statement.</d
27240 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
27250 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
27260 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 P]] ^(<dt>SQLITE
27270 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f _LIMIT_VDBE_OP</
27280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
27290 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
272a0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e instructions in
272b0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 a virtual machi
272c0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 ne program.** us
272d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
272e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
272f0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 . This limit is
27300 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a not currently.*
27310 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 * enforced, thou
27320 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 gh that might be
27330 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 added in some f
27340 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
27350 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e .** SQLite.</dd>
27360 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
27370 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
27380 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c _ARG]] ^(<dt>SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
273a0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c ON_ARG</dt>.** <
273b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
273c0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
273d0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e ts on a function
273e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
273f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 [SQLITE_LIMIT_AT
27400 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 TACHED]] ^(<dt>S
27410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
27420 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHED</dt>.** <dd
27430 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
27440 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c ber of [ATTACH |
27450 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
27460 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a ses].)^</dd>.**.
27470 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
27480 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
27490 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 ENGTH]].** ^(<dt
274a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 >SQLITE_LIMIT_LI
274b0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
274c0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
274d0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
274e0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 of the pattern
274f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
27500 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c [LIKE] or.** [GL
27510 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f OB] operators.</
27520 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
27530 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
27540 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 BLE_NUMBER]].**
27550 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
27560 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
27570 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ER</dt>.** <dd>T
27580 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 he maximum index
27590 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b number of any [
275a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e parameter] in an
275b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 SQL statement.)
275c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
275d0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
275e0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c EPTH]] ^(<dt>SQL
275f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 ITE_LIMIT_TRIGGE
27600 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
27610 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
27620 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 depth of recursi
27630 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e on for triggers.
27640 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
27650 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
27660 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 TE_LIMIT_LENGTH
27670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27680 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
27690 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
276a0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
276b0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
276c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
276d0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 N
276e0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
276f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
27700 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
27710 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
27720 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
27730 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 POUND_SELECT
27740 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
27750 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 SQLITE_LIMIT_VD
27760 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 BE_OP
27770 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
27780 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 e SQLITE_LIMIT_F
27790 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 UNCTION_ARG
277a0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
277b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
277c0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 ATTACHED
277d0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
277e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
277f0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
27800 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 NGTH 8.#de
27810 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
27820 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
27830 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 R 9.#d
27840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
27850 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
27860 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 10..
27870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27880 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
27890 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
278a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
278b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
278c0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
278d0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
278e0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
278f0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
27900 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
27910 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
27920 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
27930 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
27940 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
27950 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
27960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
27970 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
27980 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
27990 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
279a0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
279b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
279c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
279d0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
279e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
279f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
27a00 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
27a10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
27a20 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
27a30 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
27a40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
27a50 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
27a60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
27a70 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
27a80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
27a90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
27aa0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
27ab0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
27ac0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
27ad0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
27ae0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
27af0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
27b00 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
27b10 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
27b20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
27b30 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 o, then zSql is
27b40 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
27b50 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
27b60 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
27b70 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
27b80 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
27b90 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 he maximum.** nu
27ba0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 mber of bytes r
27bb0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
27bc0 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e ^When nByte is n
27bd0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
27be0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 .** zSql string
27bf0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 ends at either t
27c00 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 he first '\000'
27c10 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 or '\u0000' char
27c20 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 acter or.** the
27c30 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 nByte-th byte, w
27c40 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
27c50 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c irst. If the cal
27c60 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 ler knows.** tha
27c70 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
27c80 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
27c90 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 minated, then th
27ca0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a ere is a small.*
27cb0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 * performance ad
27cc0 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 vantage to be ga
27cd0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ined by passing
27ce0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
27cf0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 er that.** is eq
27d00 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 ual to the numbe
27d10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
27d20 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
27d30 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
27d40 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
27d50 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 nator bytes as t
27d60 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 his saves SQLite
27d70 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a from having to.
27d80 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f ** make a copy o
27d90 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 f the input stri
27da0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a ng..**.** ^If pz
27db0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
27dc0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 then *pzTail is
27dd0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
27de0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 o the first byte
27df0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 .** past the end
27e00 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 of the first SQ
27e10 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a L statement in z
27e20 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 Sql. These rout
27e30 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d ines only.** com
27e40 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 pile the first s
27e50 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
27e60 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 , so *pzTail is
27e70 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
27e80 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 .** what remains
27e90 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a uncompiled..**.
27ea0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c ** ^*ppStmt is l
27eb0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
27ec0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
27ed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
27ee0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
27ef0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
27f00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
27f10 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e ^If there is an
27f20 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
27f30 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
27f40 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 L. ^If the inpu
27f50 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
27f60 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
27f70 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
27f80 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
27f90 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
27fa0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
27fb0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
27fc0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
27fd0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
27fe0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
27ff0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
28000 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
28010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
28020 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
28030 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
28040 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
28050 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
28060 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c .** ^On success,
28070 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 the sqlite3_pre
28080 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 pare() family of
28090 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
280a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a [SQLITE_OK];.**
280b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
280c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
280d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
280e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
280f0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
28100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
28110 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
28120 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
28130 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
28140 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
28150 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
28160 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
28170 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
28180 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
28190 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
281a0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e couraged..** ^In
281b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
281c0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
281d0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
281e0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
281f0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
28200 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
28210 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
28220 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
28230 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
28240 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
28250 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
28260 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
28270 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e e differently in
28280 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a three ways:.**.
28290 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
282a0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
282b0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
282c0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
282d0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
282e0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
282f0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
28300 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
28310 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
28320 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
28330 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
28340 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
28350 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
28360 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
28370 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e <li>.** ^When an
28380 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
28390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
283a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
283b0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
283c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
283d0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
283e0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 ror codes]. ^Th
283f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
28400 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 r was that.** [s
28410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
28420 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e ould only return
28430 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 a generic [SQLI
28440 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 TE_ERROR] result
28450 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 code.** and the
28460 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 application wou
28470 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
28480 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
28490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
284a0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 )].** in order t
284b0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
284c0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
284d0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
284e0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
284f0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
28500 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
28510 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
28520 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
28530 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
28540 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
28550 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 >.** ^If the spe
28560 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e cific value boun
28570 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 d to [parameter
28580 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
28590 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 ] in the .** WHE
285a0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 RE clause might
285b0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 influence the ch
285c0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
285d0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 an for a stateme
285e0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 nt,.** then the
285f0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
28600 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
28610 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 recompiled, as i
28620 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
28630 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 .** a schema ch
28640 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 ange, on the fir
28650 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 st [sqlite3_ste
28660 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
28670 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a ing any change.*
28680 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
28690 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
286a0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 ndings] of that
286b0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
286c0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 ^The specific v
286d0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c alue of WHERE-cl
286e0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d ause [parameter]
286f0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
28700 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 the .** choice
28710 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 of query plan if
28720 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
28730 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 s the left-hand
28740 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d side of a [LIKE]
28750 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 .** or [GLOB] op
28760 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 erator or if the
28770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f parameter is co
28780 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 mpared to an ind
28790 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 exed column.** a
287a0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 nd the [SQLITE_E
287b0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d NABLE_STAT3] com
287c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
287d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 is enabled..**
287e0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a the .** </li>.**
287f0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 </ol>.*/.SQLITE
28800 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
28810 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 _prepare(. sqli
28820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
28830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
28840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
28850 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
28860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
28870 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
28880 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
28890 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
288a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
288b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
288c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
288d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
288e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
288f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
28900 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
28910 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
28920 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
28930 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
28940 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 l */.);.SQLITE_A
28950 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
28960 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
28970 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
28980 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
28990 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
289a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
289b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
289c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
289d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
289e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
289f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
28a00 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
28a10 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
28a20 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
28a30 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
28a40 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
28a50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
28a60 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
28a70 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
28a80 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
28a90 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
28aa0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
28ab0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c prepare16(. sql
28ac0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
28ad0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
28ae0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
28af0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
28b00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
28b10 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
28b20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
28b30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
28b40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
28b50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
28b60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
28b70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
28b80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
28b90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
28ba0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
28bb0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
28bc0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
28bd0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
28be0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 Sql */.);.SQLITE
28bf0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
28c00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 _prepare16_v2(.
28c10 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
28c20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
28c30 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
28c40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
28c50 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
28c60 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
28c70 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
28c80 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
28c90 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
28ca0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
28cb0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
28cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28cd0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28ce0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
28cf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
28d00 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
28d10 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
28d20 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
28d30 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f of zSql */.);../
28d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
28d50 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d etrieving Statem
28d60 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 ent SQL.**.** ^T
28d70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
28d80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 n be used to ret
28d90 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f rieve a saved co
28da0 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e py of the origin
28db0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 al.** SQL text u
28dc0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 sed to create a
28dd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28de0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 ent] if that sta
28df0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f tement was.** co
28e00 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 mpiled using eit
28e10 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 her [sqlite3_pre
28e20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
28e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
28e40 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 _v2()]..*/.SQLIT
28e50 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
28e60 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 *sqlite3_sql(sq
28e70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
28e80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
28e90 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
28ea0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
28eb0 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 nt Writes The Da
28ec0 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 tabase.**.** ^Th
28ed0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
28ee0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 eadonly(X) inter
28ef0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
28f00 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a e (non-zero) if.
28f10 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 ** and only if t
28f20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
28f30 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 tement] X makes
28f40 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 no direct change
28f50 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 s to.** the cont
28f60 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
28f70 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
28f80 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 Note that [appli
28f90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
28fa0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 QL functions] or
28fb0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
28fc0 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 les] might chang
28fd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 e the database i
28fe0 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 ndirectly as a s
28ff0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a ide effect. .**
29000 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
29010 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
29020 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 n defines a func
29030 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 tion "eval()" th
29040 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 at .** calls [sq
29050 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 lite3_exec()], t
29060 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e hen the followin
29070 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 g SQL statement
29080 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 would.** change
29090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
290a0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 e through side-e
290b0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ffects:.**.** <b
290c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
290d0 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 ** SELECT eva
290e0 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 l('DELETE FROM t
290f0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 1') FROM t2;.**
29100 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
29110 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 te>.**.** But be
29120 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 cause the [SELEC
29130 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 T] statement doe
29140 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
29150 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
29160 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 * directly, sqli
29170 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
29180 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 y() would still
29190 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a return true.)^.*
291a0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f *.** ^Transactio
291b0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d n control statem
291c0 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 ents such as [BE
291d0 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 GIN], [COMMIT],
291e0 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b [ROLLBACK],.** [
291f0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 SAVEPOINT], and
29200 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 [RELEASE] cause
29210 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
29220 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
29230 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 n true,.** since
29240 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 the statements
29250 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f themselves do no
29260 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 t actually modif
29270 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 y the database b
29280 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 ut.** rather the
29290 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 y control the ti
292a0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 ming of when oth
292b0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f er statements mo
292c0 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 dify the .** dat
292d0 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 abase. ^The [AT
292e0 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 TACH] and [DETAC
292f0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c H] statements al
29300 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 so cause.** sqli
29310 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
29320 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
29330 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 ue since, while
29340 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 those statements
29350 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 .** change the c
29360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 onfiguration of
29370 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
29380 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e ction, they do n
29390 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e ot make .** chan
293a0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 ges to the conte
293b0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
293c0 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b se files on disk
293d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
293e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
293f0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 _readonly(sqlite
29400 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
29410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
29420 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 Determine If A
29430 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
29440 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 nt Has Been Rese
29450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
29460 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 ite3_stmt_busy(S
29470 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
29480 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 rns true (non-ze
29490 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 ro) if the.** [p
294a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
294b0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 t] S has been st
294c0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f epped at least o
294d0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 nce using .** [s
294e0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
294f0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 but has not run
29500 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e to completion an
29510 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a d/or has not .**
29520 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e been reset usin
29530 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
29540 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 (S)]. ^The sqli
29550 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
29560 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
29570 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 turns false if S
29580 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
29590 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 er. If S is not
295a0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e a .** NULL poin
295b0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ter and is not a
295c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 pointer to a va
295d0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 lid [prepared st
295e0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
295f0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ct, then the beh
29600 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
29610 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
29620 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a undesirable..**.
29630 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
29640 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e e can be used in
29650 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 combination [sq
29660 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
29670 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 )].** to locate
29680 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 all prepared sta
29690 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 tements associat
296a0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 ed with a databa
296b0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f se .** connectio
296c0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 n that are in ne
296d0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 ed of being rese
296e0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 t. This can be
296f0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 used,.** for exa
29700 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 mple, in diagnos
29710 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 tic routines to
29720 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 search for prepa
29730 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e red .** statemen
29740 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 ts that are hold
29750 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f ing a transactio
29760 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 n open..*/.SQLIT
29770 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
29780 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 3_stmt_busy(sqli
29790 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
297a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e ** CAPI3REF: Dyn
297b0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
297c0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b alue Object.** K
297d0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
297e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
297f0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
29800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
29810 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
29820 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
29830 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
29840 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
29850 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
29860 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
29870 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
29880 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
29890 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
298a0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
298b0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 res. ^Values st
298c0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
298d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a value objects.**
298e0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 can be integers
298f0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 , floating point
29900 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 values, strings
29910 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c , BLOBs, or NULL
29920 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 ..**.** An sqlit
29930 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
29940 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 may be either "p
29950 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e rotected" or "un
29960 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 protected"..** S
29970 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 ome interfaces r
29980 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 equire a protect
29990 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
299a0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 . Other interfa
299b0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 ces.** will acce
299c0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 pt either a prot
299d0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 ected or an unpr
299e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
299f0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 value..** Every
29a00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
29a10 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 ccepts sqlite3_v
29a20 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 alue arguments s
29a30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 pecifies.** whet
29a40 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
29a50 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
29a60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
29a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
29a80 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
29a90 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
29aa0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
29ab0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
29ac0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 ex is held. An
29ad0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 internal mutex i
29ae0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f s held for a pro
29af0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
29b00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 3_value object b
29b10 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 ut no mutex is h
29b20 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f eld for an unpro
29b30 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
29b40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 3_value object.
29b50 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
29b60 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e mpiled to be sin
29b70 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 gle-threaded.**
29b80 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 (with [SQLITE_TH
29b90 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 READSAFE=0] and
29ba0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 with [sqlite3_th
29bb0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 readsafe()] retu
29bc0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 rning 0).** or i
29bd0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 f SQLite is run
29be0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 in one of reduce
29bf0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a d mutex modes .*
29c00 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
29c10 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f _SINGLETHREAD] o
29c20 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
29c30 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a _MULTITHREAD].**
29c40 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e then there is n
29c50 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 o distinction be
29c60 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
29c70 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
29c80 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
29c90 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 objects and the
29ca0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e y can be used in
29cb0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 terchangeably.
29cc0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 However,.** for
29cd0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 maximum code por
29ce0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 tability it is r
29cf0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
29d00 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
29d10 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 still make the d
29d20 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
29d30 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
29d40 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
29d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29d60 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 jects even when
29d70 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 not strictly req
29d80 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 uired..**.** ^Th
29d90 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
29da0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 objects that are
29db0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d passed as param
29dc0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a eters into the.*
29dd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
29de0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e of [application
29df0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
29e00 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 ctions] are prot
29e10 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 ected..** ^The s
29e20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29e30 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
29e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
29e50 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
29e60 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 nprotected..** U
29e70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
29e80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
29e90 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
29ea0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 d with.** [sqlit
29eb0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
29ec0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
29ed0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a bind_value()]..*
29ee0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 * The [sqlite3_v
29ef0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 alue_blob | sqli
29f00 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 te3_value_type()
29f10 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 ] family of.** i
29f20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
29f30 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 e protected sqli
29f40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
29f50 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 s..*/.typedef st
29f60 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 ruct Mem sqlite3
29f70 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _value;../*.** C
29f80 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e API3REF: SQL Fun
29f90 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
29fa0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
29fb0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
29fc0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
29fd0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
29fe0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
29ff0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
2a000 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 ct. ^A pointer
2a010 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f to an sqlite3_co
2a020 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 ntext object.**
2a030 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 is always first
2a040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 parameter to [ap
2a050 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2a060 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2a070 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
2a080 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2a090 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
2a0a0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 entation will pa
2a0b0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 ss this.** point
2a0c0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 er through into
2a0d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2a0e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 3_result_int | s
2a0f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d qlite3_result()]
2a100 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 ,.** [sqlite3_ag
2a110 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
2a120 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 )], [sqlite3_use
2a130 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 r_data()],.** [s
2a140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
2a150 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 b_handle()], [sq
2a160 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
2a170 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 a()],.** and/or
2a180 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 [sqlite3_set_aux
2a190 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 data()]..*/.type
2a1a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2a1b0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 e3_context sqlit
2a1c0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a e3_context;../*.
2a1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e ** CAPI3REF: Bin
2a1e0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 ding Values To P
2a1f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2a200 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ts.** KEYWORDS:
2a210 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d {host parameter}
2a220 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2a230 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 s} {host paramet
2a240 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 er name}.** KEYW
2a250 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d ORDS: {SQL param
2a260 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d eter} {SQL param
2a270 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 eters} {paramete
2a280 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a r binding}.**.**
2a290 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 ^(In the SQL st
2a2a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 atement text inp
2a2b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 ut to [sqlite3_p
2a2c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2a2d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a its variants,.*
2a2e0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 * literals may b
2a2f0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 e replaced by a
2a300 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 [parameter] that
2a310 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 matches one of
2a320 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d following.** tem
2a330 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 plates:.**.** <u
2a340 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a l>.** <li> ?.**
2a350 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c <li> ?NNN.** <
2a360 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 li> :VVV.** <li
2a370 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > @VVV.** <li>
2a380 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a $VVV.** </ul>.*
2a390 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 *.** In the temp
2a3a0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e lates above, NNN
2a3b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 represents an i
2a3c0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a nteger literal,.
2a3d0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 ** and VVV repre
2a3e0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 sents an alphanu
2a3f0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 meric identifier
2a400 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 .)^ ^The values
2a410 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 of these.** par
2a420 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 ameters (also ca
2a430 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d lled "host param
2a440 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 eter names" or "
2a450 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 SQL parameters")
2a460 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 .** can be set u
2a470 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
2a480 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2a490 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e es defined here.
2a4a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2a4b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
2a4c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2a4d0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 () routines is a
2a4e0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 lways.** a point
2a4f0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
2a500 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 e3_stmt] object
2a510 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a returned from.**
2a520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2a530 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 e_v2()] or its v
2a540 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e ariants..**.** ^
2a550 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
2a560 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
2a570 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 of the SQL para
2a580 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e meter to be set.
2a590 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 .** ^The leftmos
2a5a0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 t SQL parameter
2a5b0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
2a5c0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 1. ^When the sa
2a5d0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 me named.** SQL
2a5e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 parameter is use
2a5f0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 d more than once
2a600 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 , second and sub
2a610 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 sequent.** occur
2a620 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 rences have the
2a630 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 same index as th
2a640 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e e first occurren
2a650 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 ce..** ^The inde
2a660 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 x for named para
2a670 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f meters can be lo
2a680 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 oked up using th
2a690 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 e.** [sqlite3_bi
2a6a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2a6b0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 ex()] API if des
2a6c0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 ired. ^The inde
2a6d0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 x.** for "?NNN"
2a6e0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 parameters is th
2a6f0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a e value of NNN..
2a700 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 ** ^The NNN valu
2a710 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
2a720 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c n 1 and the [sql
2a730 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
2a740 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 parameter [SQLI
2a750 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
2a760 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 E_NUMBER] (defau
2a770 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a lt value: 999)..
2a780 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
2a790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
2a7a0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 value to bind t
2a7b0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e o the parameter.
2a7c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
2a7d0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
2a7e0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
2a7f0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
2a800 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
2a810 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2a820 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
2a830 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
2a840 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
2a850 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
2a860 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
2a870 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
2a880 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
2a890 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
2a8a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2a8b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
2a8c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
2a8d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 string is.** the
2a8e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2a8f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
2a900 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2a910 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 ..** If a non-ne
2a920 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 gative fourth pa
2a930 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 rameter is provi
2a940 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ded to sqlite3_b
2a950 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 ind_text().** or
2a960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2a970 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 xt16() then that
2a980 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
2a990 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
2a9a0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 et.** where the
2a9b0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
2a9c0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d ould occur assum
2a9d0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 ing the string w
2a9e0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 ere NUL.** termi
2a9f0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
2aa00 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
2aa10 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 cur at byte offs
2aa20 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a ets less than .*
2aa30 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * the value of t
2aa40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2aa50 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 ter then the res
2aa60 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 ulting string va
2aa70 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 lue will.** cont
2aa80 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ain embedded NUL
2aa90 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f s. The result o
2aaa0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e f expressions in
2aab0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a volving strings.
2aac0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 ** with embedded
2aad0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
2aae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
2aaf0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
2ab00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2ab10 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 ob(), sqlite3_bi
2ab20 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a nd_text(), and.*
2ab30 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
2ab40 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 ext16() is a des
2ab50 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
2ab60 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
2ab70 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
2ab80 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
2ab90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
2aba0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 it. ^The destru
2abb0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a ctor is called.*
2abc0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 * to dispose of
2abd0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 the BLOB or stri
2abe0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 ng even if the c
2abf0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 all to sqlite3_b
2ac00 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 ind_blob(),.** s
2ac10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2ac20 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 (), or sqlite3_b
2ac30 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 ind_text16() fai
2ac40 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 ls. .** ^If the
2ac50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2ac60 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 is.** the specia
2ac70 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f l value [SQLITE_
2ac80 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 STATIC], then SQ
2ac90 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
2aca0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 t the.** informa
2acb0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 tion is in stati
2acc0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 c, unmanaged spa
2acd0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 ce and does not
2ace0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 need to be freed
2acf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 ..** ^If the fif
2ad00 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 th argument has
2ad10 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 the value [SQLIT
2ad20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 E_TRANSIENT], th
2ad30 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b en.** SQLite mak
2ad40 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 es its own priva
2ad50 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 te copy of the d
2ad60 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c ata immediately,
2ad70 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 before.** the s
2ad80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2ad90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e routine returns.
2ada0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2adb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2adc0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 b() routine bind
2add0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 s a BLOB of leng
2ade0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 th N that.** is
2adf0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f filled with zero
2ae00 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 es. ^A zeroblob
2ae10 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
2ae20 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
2ae30 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
2ae40 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
2ae50 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
2ae60 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
2ae70 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
2ae80 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
2ae90 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
2aea0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
2aeb0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
2aec0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
2aed0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2aee0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
2aef0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
2af00 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
2af10 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 * ^A negative va
2af20 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
2af30 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
2af40 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
2af50 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e OB..**.** ^If an
2af60 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
2af70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2af80 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
2af90 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
2afa0 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
2afb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2afc0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
2afd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
2afe0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
2aff0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2b000 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
2b010 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
2b020 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2b030 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
2b040 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
2b050 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2b060 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
2b070 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
2b080 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
2b090 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b0a0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
2b0b0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
2b0c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
2b0d0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
2b0e0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
2b0f0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
2b100 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
2b110 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
2b120 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
2b130 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
2b140 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
2b150 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
2b160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b170 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
2b180 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
2b190 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
2b1a0 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
2b1b0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
2b1c0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
2b1d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 ** ^[SQLITE_RANG
2b1e0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 E] is returned i
2b1f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a f the parameter.
2b200 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 ** index is out
2b210 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c of range. ^[SQL
2b220 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 ITE_NOMEM] is re
2b230 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 turned if malloc
2b240 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 () fails..**.**
2b250 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2b260 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b270 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b r_count()],.** [
2b280 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b290 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
2b2a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e and [sqlite3_bin
2b2b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2b2c0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2b2d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2b2e0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 bind_blob(sqlite
2b2f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2b300 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e nst void*, int n
2b310 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2b320 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b330 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 t sqlite3_bind_d
2b340 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2b350 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 mt*, int, double
2b360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b370 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
2b380 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
2b390 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c , int, int);.SQL
2b3a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2b3b0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 te3_bind_int64(s
2b3c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b3d0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
2b3e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b3f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
2b400 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
2b410 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
2b420 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2b430 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 bind_text(sqlite
2b440 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2b450 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e nst char*, int n
2b460 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2b470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2b480 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
2b490 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
2b4a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2b4b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2b4e0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 te3_bind_value(s
2b4f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b500 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 t, const sqlite3
2b510 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
2b520 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2b530 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
2b540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b550 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
2b560 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2b570 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
2b580 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
2b590 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2b5a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
2b5b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
2b5c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
2b5d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2b5e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
2b5f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
2b600 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
2b610 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
2b620 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
2b630 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
2b640 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
2b650 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
2b660 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
2b670 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2b680 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
2b690 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
2b6a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
2b6b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
2b6c0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
2b6d0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
2b6e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
2b6f0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
2b700 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
2b710 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
2b720 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
2b730 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
2b740 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
2b750 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
2b760 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
2b770 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
2b780 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
2b790 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
2b7a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
2b7b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2b7c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2b7d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2b7e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2b7f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2b800 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2b810 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2b820 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2b830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2b840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2b850 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c ameter_count(sql
2b860 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2b870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
2b880 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 me Of A Host Par
2b890 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 ameter.**.** ^Th
2b8a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 e sqlite3_bind_p
2b8b0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c arameter_name(P,
2b8c0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 N) interface ret
2b8d0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 urns.** the name
2b8e0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 of the N-th [SQ
2b8f0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 L parameter] in
2b900 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2b910 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e atement] P..** ^
2b920 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 (SQL parameters
2b930 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e of the form "?NN
2b940 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
2b950 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
2b960 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 .** have a name
2b970 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 which is the str
2b980 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a ing "?NNN" or ":
2b990 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
2b9a0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 r "$AAA".** resp
2b9b0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 ectively..** In
2b9c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
2b9d0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
2b9e0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f "$" or "@" or "?
2b9f0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 ".** is included
2ba00 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
2ba10 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 name.)^.** ^Para
2ba20 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f meters of the fo
2ba30 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 rm "?" without a
2ba40 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 following integ
2ba50 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a er have no name.
2ba60 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 ** and are refer
2ba70 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c red to as "namel
2ba80 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f ess" or "anonymo
2ba90 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a us parameters"..
2baa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
2bab0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 host parameter
2bac0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 has an index of
2bad0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 1, not 0..**.**
2bae0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 ^If the value N
2baf0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 is out of range
2bb00 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 or if the N-th p
2bb10 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e arameter is.** n
2bb20 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 ameless, then NU
2bb30 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 LL is returned.
2bb40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2bb50 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 tring is.** alwa
2bb60 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f ys in UTF-8 enco
2bb70 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ding even if the
2bb80 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
2bb90 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c was.** original
2bba0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ly specified as
2bbb0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 UTF-16 in [sqlit
2bbc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
2bbd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 or.** [sqlite3_p
2bbe0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
2bbf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2bc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2bc10 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
2bc20 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2bc30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
2bc40 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
2bc50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2bc60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2bc70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2bc80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2bc90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2bca0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f er_name(sqlite3_
2bcb0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a stmt*, int);../*
2bcc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
2bcd0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 dex Of A Paramet
2bce0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 er With A Given
2bcf0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 Name.**.** ^Retu
2bd00 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 rn the index of
2bd10 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 an SQL parameter
2bd20 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
2bd30 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 ^The.** index
2bd40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
2bd50 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 s suitable for u
2bd60 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 se as the second
2bd70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
2bd80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2bd90 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2bda0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a ()]. ^A zero.**
2bdb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2bdc0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 no matching para
2bdd0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 meter is found.
2bde0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a ^The parameter.
2bdf0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 ** name must be
2be00 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 given in UTF-8 e
2be10 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 ven if the origi
2be20 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a nal statement.**
2be30 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 was prepared fr
2be40 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 om UTF-16 text u
2be50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
2be60 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2be70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2be80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2be90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2bea0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2beb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2bec0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
2bed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2bee0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2bef0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2bf00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2bf10 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2bf20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 sqlite3_stmt*, c
2bf30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
2bf40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2bf50 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 EF: Reset All Bi
2bf60 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 ndings On A Prep
2bf70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a ared Statement.*
2bf80 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 *.** ^Contrary t
2bf90 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
2bfa0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
2bfb0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
2bfc0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 not reset.** the
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2bfe0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
2bff0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
2c000 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 tatement]..** ^U
2c010 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
2c020 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
2c030 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
2c040 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f NULL..*/.SQLITE_
2c050 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2c060 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 clear_bindings(s
2c070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
2c080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2c090 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e Number Of Column
2c0a0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
2c0b0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 t.**.** ^Return
2c0c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
2c0d0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
2c0e0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
2c0f0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 by the.** [prep
2c100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2c110 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
2c120 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d eturns 0 if pStm
2c130 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 t is an SQL.** s
2c140 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f tatement that do
2c150 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 es not return da
2c160 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ta (for example
2c170 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a an [UPDATE])..**
2c180 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2c190 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2c1a0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 t()].*/.SQLITE_A
2c1b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
2c1c0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 olumn_count(sqli
2c1d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2c1e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2c1f0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 F: Column Names
2c200 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a In A Result Set.
2c210 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2c220 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
2c230 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
2c240 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
2c250 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
2c260 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
2c270 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2c280 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 nt. ^The sqlite
2c290 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
2c2a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
2c2b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2c2c0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
2c2d0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
2c2e0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
2c2f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
2c300 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2c310 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
2c320 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
2c330 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 string. ^The f
2c340 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
2c350 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
2c360 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
2c370 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
2c380 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
2c390 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e ment. ^The secon
2c3a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
2c3b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d he.** column num
2c3c0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d ber. ^The leftm
2c3d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
2c3e0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mber 0..**.** ^T
2c3f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
2c400 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
2c410 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
2c420 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2c430 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
2c440 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
2c450 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2c460 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
2c470 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
2c480 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
2c490 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
2c4a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
2c4b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
2c4c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
2c4d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
2c4e0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a he next call to.
2c4f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
2c500 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
2c510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
2c520 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 6() on the same
2c530 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 column..**.** ^I
2c540 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
2c550 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
2c560 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
2c570 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
2c580 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
2c590 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
2c5a0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
2c5b0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
2c5c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
2c5d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
2c5e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
2c5f0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d f a result colum
2c600 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f n is the value o
2c610 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 f the "AS" claus
2c620 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f e for.** that co
2c630 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 lumn, if there i
2c640 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 s an AS clause.
2c650 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
2c660 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 AS clause.** the
2c670 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2c680 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 e column is unsp
2c690 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 ecified and may
2c6a0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f change from.** o
2c6b0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ne release of SQ
2c6c0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 Lite to the next
2c6d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2c6e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2c6f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2c700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2c710 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt N);.SQLITE_AP
2c720 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2c730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2c740 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2c750 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a *, int N);../*.*
2c760 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 * CAPI3REF: Sour
2c770 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 ce Of Data In A
2c780 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a Query Result.**.
2c790 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2c7a0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
2c7b0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
2c7c0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 the database, ta
2c7d0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c ble, and.** tabl
2c7e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 e column that is
2c7f0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 the origin of a
2c800 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 particular resu
2c810 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 lt column in.**
2c820 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2c830 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 nt..** ^The name
2c840 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2c850 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
2c860 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
2c870 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
2c880 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
2c890 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
2c8a0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 _database_ rout
2c8b0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 ines return.** t
2c8c0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
2c8d0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f , the _table_ ro
2c8e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2c8f0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e e table name, an
2c900 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f d.** the origin_
2c910 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2c920 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 the column name
2c930 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
2c940 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
2c950 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
2c960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c970 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
2c980 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
2c990 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2c9a0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2c9b0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2c9c0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2c9d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2c9e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2c9f0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2ca00 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2ca10 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
2ca20 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
2ca30 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
2ca40 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
2ca50 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
2ca60 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
2ca70 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
2ca80 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
2ca90 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
2caa0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
2cab0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
2cac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2cad0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
2cae0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
2caf0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
2cb00 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
2cb10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2cb20 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
2cb30 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
2cb40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
2cb50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
2cb60 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
2cb70 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
2cb80 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
2cb90 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
2cba0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
2cbb0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
2cbc0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
2cbd0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
2cbe0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
2cbf0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
2cc00 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
2cc10 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
2cc20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
2cc30 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
2cc40 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
2cc50 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
2cc60 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
2cc70 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
2cc80 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
2cc90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
2cca0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
2ccb0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
2ccc0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
2ccd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
2cce0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2ccf0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
2cd00 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
2cd10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
2cd20 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
2cd30 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
2cd40 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
2cd50 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
2cd60 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
2cd70 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
2cd80 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
2cd90 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
2cda0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
2cdb0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
2cdc0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
2cdd0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
2cde0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
2cdf0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
2ce00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
2ce10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
2ce20 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
2ce30 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
2ce40 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
2ce50 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
2ce60 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
2ce70 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
2ce80 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
2ce90 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
2cea0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
2ceb0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
2cec0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
2ced0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
2cee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2cef0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
2cf00 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
2cf10 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
2cf20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2cf30 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
2cf40 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
2cf50 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
2cf60 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
2cf70 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
2cf80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
2cf90 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
2cfa0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
2cfb0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2cfc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2cfd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2cfe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2cff0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
2d000 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2d010 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2d020 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2d030 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2d040 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2d050 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2d060 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
2d070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
2d080 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f le_name(sqlite3_
2d090 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2d0a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2d0b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2d0c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
2d0d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2d0e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2d0f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2d100 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2d110 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2d120 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2d130 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2d140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
2d150 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c rigin_name16(sql
2d160 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2d170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2d180 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 : Declared Datat
2d190 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 ype Of A Query R
2d1a0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 esult.**.** ^(Th
2d1b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2d1c0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 r is a [prepared
2d1d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2d1e0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
2d1f0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 t is a [SELECT]
2d200 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 statement and th
2d210 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
2d220 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 the.** returned
2d230 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
2d240 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 at [SELECT] is a
2d250 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
2d260 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
2d270 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
2d280 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
2d290 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
2d2a0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
2d2b0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e s returned.)^ ^
2d2c0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
2d2d0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
2d2e0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
2d2f0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
2d300 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
2d310 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
2d320 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 rned..** ^The re
2d330 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
2d340 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e always UTF-8 en
2d350 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 coded..**.** ^(F
2d360 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 or example, give
2d370 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 n the database s
2d380 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 chema:.**.** CRE
2d390 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 ATE TABLE t1(c1
2d3a0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 VARIANT);.**.**
2d3b0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e and the followin
2d3c0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 g statement to b
2d3d0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a e compiled:.**.*
2d3e0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
2d3f0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
2d400 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ** this routine
2d410 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 would return the
2d420 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 string "VARIANT
2d430 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 " for the second
2d440 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d result.** colum
2d450 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 n (i==1), and a
2d460 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
2d470 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c the first resul
2d480 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e t column (i==0).
2d490 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
2d4a0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
2d4b0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
2d4c0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 ^So just because
2d4d0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 a column.** is
2d4e0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 declared to cont
2d4f0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ain a particular
2d500 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d type does not m
2d510 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ean that the.**
2d520 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 data stored in t
2d530 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 hat column is of
2d540 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
2d550 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a pe. SQLite is.*
2d560 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 * strongly typed
2d570 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 , but the typing
2d580 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 is dynamic not
2d590 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a static. ^Type.*
2d5a0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 * is associated
2d5b0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 with individual
2d5c0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 values, not with
2d5d0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a the containers.
2d5e0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ** used to hold
2d5f0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f those values..*/
2d600 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2d610 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2d620 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
2d630 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2d640 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2d650 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2d660 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
2d670 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
2d680 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
2d690 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
2d6a0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
2d6b0 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 ent.**.** After
2d6c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2d6d0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 ement] has been
2d6e0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 prepared using e
2d6f0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ither.** [sqlite
2d700 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2d710 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2d720 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f are16_v2()] or o
2d730 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ne of the legacy
2d740 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b .** interfaces [
2d750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
2d760 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
2d770 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 repare16()], thi
2d780 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 s function.** mu
2d790 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 st be called one
2d7a0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
2d7b0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 o evaluate the s
2d7c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
2d7d0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
2d7e0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
2d7f0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
2d800 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 ) interface depe
2d810 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 nd.** on whether
2d820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
2d830 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e as prepared usin
2d840 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 g the newer "v2"
2d850 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 interface.** [s
2d860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2d870 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
2d880 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2d890 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c ] or the older l
2d8a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2d8b0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ce [sqlite3_prep
2d8c0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 are()] and [sqli
2d8d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
2d8e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2d8f0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e e.** new "v2" in
2d900 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
2d910 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 mended for new a
2d920 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 pplications but
2d930 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
2d940 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e terface will con
2d950 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 tinue to be supp
2d960 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e orted..**.** ^In
2d970 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
2d980 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 rface, the retur
2d990 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 n value will be
2d9a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 either [SQLITE_B
2d9b0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 USY],.** [SQLITE
2d9c0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _DONE], [SQLITE_
2d9d0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 ROW], [SQLITE_ER
2d9e0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ROR], or [SQLITE
2d9f0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 _MISUSE]..** ^Wi
2da00 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
2da10 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 rface, any of th
2da20 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 e other [result
2da30 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 codes] or.** [ex
2da40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
2da50 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 des] might be re
2da60 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a turned as well..
2da70 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 **.** ^[SQLITE_B
2da80 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USY] means that
2da90 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 the database eng
2daa0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 ine was unable t
2dab0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a o acquire the.**
2dac0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 database locks
2dad0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 it needs to do i
2dae0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 ts job. ^If the
2daf0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
2db00 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f [COMMIT].** or o
2db10 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 ccurs outside of
2db20 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
2db30 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 nsaction, then y
2db40 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 ou can retry the
2db50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 .** statement.
2db60 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 If the statement
2db70 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 is not a [COMMI
2db80 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 T] and occurs wi
2db90 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 thin an.** expli
2dba0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
2dbb0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
2dbc0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
2dbd0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
2dbe0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
2dbf0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f *.** ^[SQLITE_DO
2dc00 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 NE] means that t
2dc10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 he statement has
2dc20 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 finished execut
2dc30 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ing.** successfu
2dc40 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 lly. sqlite3_st
2dc50 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2dc60 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2dc70 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a on this virtual.
2dc80 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f ** machine witho
2dc90 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 ut first calling
2dca0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2dcb0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
2dcc0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
2dcd0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ne back to its i
2dce0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a nitial state..**
2dcf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 .** ^If the SQL
2dd00 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 statement being
2dd10 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 executed returns
2dd20 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 any data, then
2dd30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 [SQLITE_ROW].**
2dd40 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 is returned each
2dd50 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 time a new row
2dd60 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 of data is ready
2dd70 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 for processing
2dd80 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 by the.** caller
2dd90 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 . The values may
2dda0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 be accessed usi
2ddb0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 ng the [column a
2ddc0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d ccess functions]
2ddd0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 ..** sqlite3_ste
2dde0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 p() is called ag
2ddf0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 ain to retrieve
2de00 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 the next row of
2de10 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 data..**.** ^[SQ
2de20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e LITE_ERROR] mean
2de30 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d s that a run-tim
2de40 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 e error (such as
2de50 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a a constraint.**
2de60 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 violation) has
2de70 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 occurred. sqlit
2de80 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
2de90 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
2dea0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 gain on.** the V
2deb0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 M. More informat
2dec0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 ion may be found
2ded0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
2dee0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a ite3_errmsg()]..
2def0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 ** ^With the leg
2df00 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 acy interface, a
2df10 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
2df20 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 rror code (for e
2df30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 xample,.** [SQLI
2df40 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b TE_INTERRUPT], [
2df50 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 SQLITE_SCHEMA],
2df60 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
2df70 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a , and so forth).
2df80 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e ** can be obtain
2df90 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ed by calling [s
2dfa0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2dfb0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 on the.** [prepa
2dfc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
2dfd0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e ^In the "v2" in
2dfe0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 terface,.** the
2dff0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
2e000 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 ror code is retu
2e010 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 rned directly by
2e020 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
2e030 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d .**.** [SQLITE_M
2e040 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 ISUSE] means tha
2e050 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 t the this routi
2e060 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e ne was called in
2e070 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a appropriately..*
2e080 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 * Perhaps it was
2e090 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 called on a [pr
2e0a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e0b0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c ] that has.** al
2e0c0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 ready been [sqli
2e0d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
2e0e0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 inalized] or on
2e0f0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 one that had.**
2e100 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
2e110 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ned [SQLITE_ERRO
2e120 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f R] or [SQLITE_DO
2e130 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c NE]. Or it coul
2e140 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 d.** be the case
2e150 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 that the same d
2e160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2e170 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 on is being used
2e180 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f by two or.** mo
2e190 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 re threads at th
2e1a0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e e same moment in
2e1b0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 time..**.** For
2e1c0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 all versions of
2e1d0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e SQLite up to an
2e1e0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e d including 3.6.
2e1f0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 23.1, a call to.
2e200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2e210 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 t()] was require
2e220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
2e230 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 step() returned
2e240 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 anything.** othe
2e250 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
2e260 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 OW] before any s
2e270 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
2e280 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 tion of.** sqlit
2e290 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c e3_step(). Fail
2e2a0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 ure to reset the
2e2b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2e2c0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 ent using .** [s
2e2d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2e2e0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 would result in
2e2f0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 an [SQLITE_MISUS
2e300 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a E] return from.*
2e310 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
2e320 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 . But after ver
2e330 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 sion 3.6.23.1, s
2e340 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 qlite3_step() be
2e350 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b gan.** calling [
2e360 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e370 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 automatically i
2e380 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 n this circumsta
2e390 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 nce rather.** th
2e3a0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 an returning [SQ
2e3b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 LITE_MISUSE]. T
2e3c0 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 his is not consi
2e3d0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 dered a compatib
2e3e0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 ility.** break b
2e3f0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 ecause any appli
2e400 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 cation that ever
2e410 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c receives an SQL
2e420 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 ITE_MISUSE error
2e430 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 .** is broken by
2e440 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 definition. Th
2e450 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
2e460 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c UTORESET] compil
2e470 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a e-time option.**
2e480 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2e490 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 restore the lega
2e4a0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a cy behavior..**.
2e4b0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 ** <b>Goofy Inte
2e4c0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e rface Alert:</b>
2e4d0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 In the legacy i
2e4e0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 nterface, the sq
2e4f0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 lite3_step().**
2e500 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 API always retur
2e510 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 ns a generic err
2e520 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 or code, [SQLITE
2e530 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 _ERROR], followi
2e540 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 ng any.** error
2e550 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
2e560 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 TE_BUSY] and [SQ
2e570 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 LITE_MISUSE]. Y
2e580 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 ou must call.**
2e590 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2e5a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
2e5b0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 nalize()] in ord
2e5c0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f er to find one o
2e5d0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 f the.** specifi
2e5e0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
2e5f0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 that better desc
2e600 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e ribes the error.
2e610 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 .** We admit tha
2e620 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 t this is a goof
2e630 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 y design. The p
2e640 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 roblem has been
2e650 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 fixed.** with th
2e660 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2e670 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 . If you prepar
2e680 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 e all of your SQ
2e690 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
2e6a0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
2e6b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2e6c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2e6d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
2e6e0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 instead.** of th
2e6f0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 e legacy [sqlite
2e700 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 3_prepare()] and
2e710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2e720 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 e16()] interface
2e730 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d s,.** then the m
2e740 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 ore specific [er
2e750 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 ror codes] are r
2e760 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
2e770 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 .** by sqlite3_s
2e780 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 tep(). The use
2e790 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 of the "v2" inte
2e7a0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 rface is recomme
2e7b0 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f nded..*/.SQLITE_
2e7c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2e7d0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2e7e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2e7f0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2e800 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2e810 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2e820 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2e830 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2e840 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2e850 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2e860 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2e870 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2e880 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2e890 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2e8a0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2e8b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2e8c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2e8d0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2e8e0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2e8f0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2e900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2e910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e920 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2e930 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2e940 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2e950 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2e960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2e970 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2e980 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2e990 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2e9a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2e9b0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2e9c0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2e9d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2e9e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2e9f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2ea00 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2ea10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2ea20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2ea30 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2ea40 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2ea50 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2ea60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2ea70 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2ea80 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2ea90 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2eaa0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2eab0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2eac0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2ead0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2eae0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2eaf0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2eb00 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2eb10 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2eb20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2eb30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2eb40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2eb50 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c _count()].*/.SQL
2eb60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2eb70 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
2eb80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2eb90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2eba0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
2ebb0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b l Datatypes.** K
2ebc0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
2ebd0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 TEXT.**.** ^(Eve
2ebe0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
2ebf0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
2ec00 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
2ec10 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
2ec20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
2ec30 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
2ec40 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
2ec50 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
2ec60 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
2ec70 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
2ec80 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
2ec90 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NULL.** </ul>)^
2eca0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
2ecb0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
2ecc0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
2ecd0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
2ece0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
2ecf0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
2ed00 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
2ed10 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
2ed20 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
2ed30 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
2ed40 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
2ed50 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
2ed60 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
2ed70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
2ed80 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
2ed90 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
2eda0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
2edb0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
2edc0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
2edd0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
2ede0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2edf0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
2ee00 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
2ee10 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
2ee20 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
2ee30 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
2ee40 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
2ee50 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
2ee60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
2ee70 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
2ee80 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
2ee90 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
2eea0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
2eeb0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
2eec0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 uery.** KEYWORDS
2eed0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 : {column access
2eee0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a functions}.**.*
2eef0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2ef00 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c form the "resul
2ef10 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 t set" interface
2ef20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
2ef30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 outines return i
2ef40 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
2ef50 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e a single column
2ef60 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
2ef70 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 ** result row of
2ef80 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 a query. ^In e
2ef90 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
2efa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
2efb0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
2efc0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2efd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
2efe0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
2eff0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
2f000 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
2f010 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
2f020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2f030 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2f040 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
2f050 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
2f060 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
2f070 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
2f080 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
2f090 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
2f0a0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
2f0b0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . ^The leftmost
2f0c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
2f0d0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
2f0e0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 index 0..** ^Th
2f0f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
2f100 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
2f110 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 t can be determi
2f120 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ned using.** [sq
2f130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
2f140 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 nt()]..**.** If
2f150 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
2f160 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
2f170 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
2f180 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
2f190 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
2f1a0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
2f1b0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
2f1c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2f1d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2f1e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
2f1f0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
2f200 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2f210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
2f220 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
2f230 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
2f240 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
2f250 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2f260 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
2f270 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
2f280 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
2f290 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
2f2a0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
2f2b0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
2f2c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
2f2d0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
2f2e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2f2f0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
2f300 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
2f310 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
2f320 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
2f330 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
2f340 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
2f350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
2f360 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f370 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
2f380 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
2f390 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
2f3a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
2f3b0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
2f3c0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
2f3d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
2f3e0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
2f3f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
2f400 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
2f410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2f420 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2f430 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2f440 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
2f450 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
2f460 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
2f470 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
2f480 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
2f490 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 ult column. ^Th
2f4a0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 e returned value
2f4b0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
2f4c0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 TE_INTEGER],.**
2f4d0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 [SQLITE_FLOAT],
2f4e0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b [SQLITE_TEXT], [
2f4f0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 SQLITE_BLOB], or
2f500 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 [SQLITE_NULL].
2f510 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 The value.** re
2f520 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2f530 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
2f540 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 is only meaningf
2f550 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a ul if no type.**
2f560 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 conversions hav
2f570 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 e occurred as de
2f580 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 scribed below.
2f590 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e After a type con
2f5a0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 version,.** the
2f5b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
2f5c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
2f5d0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 _type() is undef
2f5e0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a ined. Future.**
2f5f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
2f600 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 ite may change t
2f610 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 he behavior of s
2f620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2f630 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e pe().** followin
2f640 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 g a type convers
2f650 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ion..**.** ^If t
2f660 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
2f670 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
2f680 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
2f690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2f6a0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
2f6b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2f6c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2f6d0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
2f6e0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2f6f0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
2f700 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
2f710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f720 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
2f730 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
2f740 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
2f750 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2f760 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
2f770 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2f780 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
2f790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2f7a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 umn_bytes() uses
2f7b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2f7c0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2f7d0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2f7e0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 o a UTF-8 string
2f7f0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
2f800 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2f810 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
2f820 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
2f830 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
2f840 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2f850 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 mn_bytes() retur
2f860 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
2f870 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2f880 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 a BLOB or UTF-1
2f890 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 6 string then th
2f8a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2f8b0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f _bytes16().** ro
2f8c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2f8d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2f8e0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
2f8f0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
2f900 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2f910 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 UTF-8 string, t
2f920 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
2f930 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e mn_bytes16() con
2f940 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
2f950 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e ing to UTF-16 an
2f960 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
2f970 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2f980 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
2f990 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
2f9a0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
2f9b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f9c0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b es16() uses.** [
2f9d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
2f9e0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
2f9f0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
2fa00 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 TF-16 string and
2fa10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
2fa20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2fa30 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
2fa40 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2fa50 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
2fa60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2fa70 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 ytes16() returns
2fa80 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 zero..**.** ^Th
2fa90 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
2faa0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
2fab0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
2fac0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 d .** [sqlite3_c
2fad0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
2fae0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 do not include
2faf0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
2fb00 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a tors at the end.
2fb10 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
2fb20 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a . ^For clarity:
2fb30 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 the values retu
2fb40 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
2fb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fb60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2fb70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2fb80 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 )] are the numbe
2fb90 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
2fba0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
2fbb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2fbc0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
2fbd0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e ^Strings return
2fbe0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
2fbf0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
2fc00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2fc10 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
2fc20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
2fc30 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d are always zero-
2fc40 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
2fc50 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
2fc60 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
2fc70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
2fc80 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
2fc90 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f LOB is a NULL po
2fca0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
2fcb0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
2fcc0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
2fcd0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
2fce0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
2fcf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2fd00 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 e] object. An u
2fd10 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2fd20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a e3_value object.
2fd30 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ** may only be u
2fd40 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 sed with [sqlite
2fd50 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 3_bind_value()]
2fd60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 and [sqlite3_res
2fd70 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ult_value()]..**
2fd80 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 If the [unprote
2fd90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2fda0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 ue] object retur
2fdb0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
2fdc0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2fdd0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e )] is used in an
2fde0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 y other way, inc
2fdf0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 luding calls.**
2fe00 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 to routines like
2fe10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2fe20 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 int()], [sqlite3
2fe30 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
2fe40 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
2fe50 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 alue_bytes()], t
2fe60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
2fe70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2fe80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
2fe90 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 nes attempt to c
2fea0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
2feb0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 where appropria
2fec0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 te. ^For.** exa
2fed0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 mple, if the int
2fee0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
2fef0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e tion is FLOAT an
2ff00 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a d a text result.
2ff10 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c ** is requested,
2ff20 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
2ff30 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e tf()] is used in
2ff40 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 ternally to perf
2ff50 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 orm the.** conve
2ff60 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 rsion automatica
2ff70 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c lly. ^(The foll
2ff80 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 owing table deta
2ff90 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 ils the conversi
2ffa0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ons.** that are
2ffb0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c applied:.**.** <
2ffc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c blockquote>.** <
2ffd0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
2ffe0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e >.** <tr><th> In
2fff0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c ternal<br>Type <
30000 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 th> Requested<br
30010 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 >Type <th> Conv
30020 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 ersion.**.** <tr
30030 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
30040 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
30050 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a d> Result is 0.*
30060 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
30070 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
30080 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
30090 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 s 0.0.** <tr><td
300a0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
300b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 TEXT <td> R
300c0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f esult is NULL po
300d0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
300e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
300f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 BLOB <td> R
30100 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f esult is NULL po
30110 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
30120 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
30130 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
30140 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 onvert from inte
30150 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 ger to float.**
30160 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
30170 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
30180 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
30190 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 ering of the int
301a0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e eger.** <tr><td>
301b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
301c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
301d0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 me as INTEGER->T
301e0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
301f0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e FLOAT <td> IN
30200 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
30210 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 vert from float
30220 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 to integer.** <t
30230 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
30240 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
30250 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
30260 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 ing of the float
30270 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
30280 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f OAT <td> BLO
30290 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
302a0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a s FLOAT->TEXT.**
302b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
302c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
302d0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 <td> Use atoi(
302e0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
302f0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f EXT <td> FLO
30300 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 AT <td> Use a
30310 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
30320 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
30330 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e BLOB <td> N
30340 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e o change.** <tr>
30350 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
30360 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
30370 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
30380 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 T then use atoi(
30390 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
303a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f LOB <td> FLO
303b0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
303c0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
303d0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 use atof().** <t
303e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
303f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
30400 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
30410 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
30420 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
30430 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
30440 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 )^.**.** The tab
30450 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 le above makes r
30460 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e eference to stan
30470 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 dard C library f
30480 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a unctions atoi().
30490 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 ** and atof().
304a0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 SQLite does not
304b0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 really use these
304c0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 functions. It
304d0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 has its.** own e
304e0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e quivalent intern
304f0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 al routines. Th
30500 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f e atoi() and ato
30510 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a f() names are.**
30520 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 used in the tab
30530 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 le for brevity a
30540 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 nd because they
30550 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 are familiar to
30560 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 most.** C progra
30570 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 mmers..**.** Not
30580 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 e that when type
30590 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 conversions occ
305a0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ur, pointers ret
305b0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a urned by prior.*
305c0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
305d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
305e0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e , sqlite3_column
305f0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a _text(), and/or.
30600 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
30610 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 n_text16() may b
30620 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
30630 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f * Type conversio
30640 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 ns and pointer i
30650 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 nvalidations mig
30660 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 ht occur.** in t
30670 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 he following cas
30680 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
30690 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
306a0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 al content is a
306b0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 BLOB and sqlite3
306c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
306d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
306e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
306f0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 ) is called. A
30700 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 zero-terminator
30710 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 might.** ne
30720 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 ed to be added t
30730 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c o the string.</l
30740 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
30750 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
30760 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 s UTF-8 text and
30770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30780 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 bytes16() or.**
30790 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
307a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
307b0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
307c0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
307d0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
307e0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a o UTF-16.</li>.*
307f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 * <li> The initi
30800 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
30810 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 F-16 text and sq
30820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30830 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 es() or.**
30840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
30850 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e ext() is called.
30860 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
30870 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
30880 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 ** to UTF-8
30890 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a .</li>.** </ul>.
308a0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f **.** ^Conversio
308b0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 ns between UTF-1
308c0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 6be and UTF-16le
308d0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 are always done
308e0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f in place and do
308f0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 .** not invalida
30900 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 te a prior point
30910 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f er, though of co
30920 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 urse the content
30930 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a of the buffer.*
30940 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 * that the prior
30950 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e pointer referen
30960 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 ces will have be
30970 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 en modified. Ot
30980 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 her kinds.** of
30990 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 conversion are d
309a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 one in place whe
309b0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 n it is possible
309c0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 , but sometimes
309d0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 they.** are not
309e0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 possible and in
309f0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f those cases prio
30a00 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 r pointers are i
30a10 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a nvalidated..**.*
30a20 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 * The safest and
30a30 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 easiest to reme
30a40 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 mber policy is t
30a50 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 o invoke these r
30a60 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e outines.** in on
30a70 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
30a80 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ng ways:.**.** <
30a90 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 ul>.** <li>sqli
30aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
30ab0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
30ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
30ad0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c es()</li>.** <l
30ae0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
30af0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 _blob() followed
30b00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
30b10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
30b20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
30b30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
30b40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
30b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
30b60 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 16()</li>.** </u
30b70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 l>.**.** In othe
30b80 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f r words, you sho
30b90 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 uld call sqlite3
30ba0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a _column_text(),.
30bb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
30bc0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c n_blob(), or sql
30bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
30be0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 16() first to fo
30bf0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a rce the result.*
30c00 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 * into the desir
30c10 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 ed format, then
30c20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
30c30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
30c40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
30c50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 mn_bytes16() to
30c60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 find the size of
30c70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f the result. Do
30c80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a not mix calls.*
30c90 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c * to sqlite3_col
30ca0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 umn_text() or sq
30cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
30cc0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 b() with calls t
30cd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
30ce0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 umn_bytes16(), a
30cf0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 nd do not mix ca
30d00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
30d10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a olumn_text16().*
30d20 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 * with calls to
30d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30d40 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ytes()..**.** ^T
30d50 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
30d60 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 rned are valid u
30d70 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 ntil a type conv
30d80 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 ersion occurs as
30d90 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 .** described ab
30da0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 ove, or until [s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
30dc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
30dd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
30de0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
30df0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 s called. ^The
30e00 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 memory space use
30e10 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 d to hold string
30e20 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 s.** and BLOBs i
30e30 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 s freed automati
30e40 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f cally. Do <b>no
30e50 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 t</b> pass the p
30e60 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
30e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
30e80 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 umn_blob()], [sq
30e90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30ea0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a t()], etc. into.
30eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
30ec0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ()]..**.** ^(If
30ed0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
30ee0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
30ef0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c during the eval
30f00 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a uation of any.**
30f10 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
30f20 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 es, a default va
30f30 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
30f40 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 The default va
30f50 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 lue.** is either
30f60 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 the integer 0,
30f70 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 the floating poi
30f80 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f nt number 0.0, o
30f90 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
30fa0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ter. Subsequent
30fb0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
30fc0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 e3_errcode()] wi
30fd0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
30fe0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a LITE_NOMEM].)^.*
30ff0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
31000 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
31010 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c _column_blob(sql
31020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
31030 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
31040 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
31050 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 lumn_bytes(sqlit
31060 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
31070 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
31080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
31090 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 mn_bytes16(sqlit
310a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
310b0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
310c0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 double sqlite3_c
310d0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
310e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
310f0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
31100 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
31110 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 lumn_int(sqlite3
31120 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
31130 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
31140 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
31150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
31160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
31170 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
31180 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 E_API const unsi
31190 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 gned char *sqlit
311a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 e3_column_text(s
311b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
311c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
311d0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
311e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
311f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
31200 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
31210 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
31220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
31230 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
31240 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
31250 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
31260 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 value *sqlite3_c
31270 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 olumn_value(sqli
31280 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
31290 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
312a0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
312b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
312c0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ent Object.**.**
312d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 ^The sqlite3_fi
312e0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f nalize() functio
312f0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 n is called to d
31300 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 elete a [prepare
31310 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
31320 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
31330 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
31340 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 of the statement
31350 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 encountered no
31360 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 errors.** or if
31370 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
31380 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c never been eval
31390 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 uated, then sqli
313a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 te3_finalize() r
313b0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 eturns.** SQLITE
313c0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f _OK. ^If the mo
313d0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
313e0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e tion of statemen
313f0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e t S failed, then
31400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 .** sqlite3_fina
31410 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 lize(S) returns
31420 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 the appropriate
31430 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a [error code] or.
31440 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 ** [extended err
31450 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
31460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e ^The sqlite3_fin
31470 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 alize(S) routine
31480 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
31490 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 t any point duri
314a0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 ng.** the life c
314b0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 ycle of [prepare
314c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a d statement] S:.
314d0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d ** before statem
314e0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 ent S is ever ev
314f0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a aluated, after.*
31500 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 * one or more ca
31510 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
31520 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 reset()], or aft
31530 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 er any call.** t
31540 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
31550 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 )] regardless of
31560 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
31570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
31580 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 s.** completed e
31590 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 xecution..**.**
315a0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 ^Invoking sqlite
315b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 3_finalize() on
315c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
315d0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
315e0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 op..**.** The ap
315f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 plication must f
31600 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 inalize every [p
31610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
31620 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 t] in order to a
31630 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 void.** resource
31640 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 leaks. It is a
31650 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 grievous error
31660 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 for the applicat
31670 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 ion to try to us
31680 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 e.** a prepared
31690 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
316a0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 it has been fina
316b0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 lized. Any use
316c0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a of a prepared.**
316d0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
316e0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e it has been fin
316f0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c alized can resul
31700 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 t in undefined a
31710 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c nd.** undesirabl
31720 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 e behavior such
31730 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 as segfaults and
31740 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e heap corruption
31750 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
31760 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
31770 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
31780 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
31790 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
317a0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
317b0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
317c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
317d0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
317e0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
317f0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
31800 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
31810 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
31820 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
31830 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
31840 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
31850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
31860 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
31870 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
31880 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
31890 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
318a0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
318b0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
318c0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
318d0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
318e0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
318f0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
31900 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
31910 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
31920 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
31930 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
31940 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
31950 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
31960 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
31970 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
31980 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
31990 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
319a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
319b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
319c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
319d0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
319e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
319f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
31a00 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
31a10 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
31a20 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
31a30 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
31a40 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
31a50 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
31a60 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
31a70 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
31a80 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
31a90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
31aa0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
31ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31ac0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
31ad0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
31ae0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
31af0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
31b00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
31b10 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
31b20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
31b30 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
31b40 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
31b50 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
31b60 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
31b70 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
31b80 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
31b90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
31ba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
31bb0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 sqlite3_reset(s
31bc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
31bd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
31be0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 3REF: Create Or
31bf0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e Redefine SQL Fun
31c00 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ctions.** KEYWOR
31c10 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 DS: {function cr
31c20 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d eation routines}
31c30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
31c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31c50 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d ed SQL function}
31c60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 .** KEYWORDS: {a
31c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31c80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
31c90 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 }.**.** ^These f
31ca0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 unctions (collec
31cb0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 tively known as
31cc0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 "function creati
31cd0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a on routines").**
31ce0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 are used to add
31cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
31d00 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 r aggregates or
31d10 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 to redefine the
31d20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 behavior.** of e
31d30 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 xisting SQL func
31d40 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
31d50 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 tes. The only d
31d60 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 ifferences betwe
31d70 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 en.** these rout
31d80 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 ines are the tex
31d90 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 t encoding expec
31da0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 ted for.** the s
31db0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
31dc0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 (the name of the
31dd0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 function being
31de0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 created).** and
31df0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 the presence or
31e00 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 absence of a des
31e10 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b tructor callback
31e20 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c for.** the appl
31e30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
31e40 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nter..**.** ^The
31e50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
31e60 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 is the [databas
31e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
31e80 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a which the SQL.*
31e90 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f * function is to
31ea0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 be added. ^If
31eb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 an application u
31ec0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e ses more than on
31ed0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
31ee0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 nnection then ap
31ef0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
31f00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
31f10 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a must be added.**
31f20 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 to each databas
31f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 e connection sep
31f40 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e arately..**.** ^
31f50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
31f60 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 eter is the name
31f70 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 of the SQL func
31f80 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 tion to be creat
31f90 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e ed or.** redefin
31fa0 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 ed. ^The length
31fb0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 of the name is
31fc0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 limited to 255 b
31fd0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a ytes in a UTF-8.
31fe0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ** representatio
31ff0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 n, exclusive of
32000 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
32010 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 tor. ^Note that
32020 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e the name.** len
32030 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 gth limit is in
32040 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 UTF-8 bytes, not
32050 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 characters nor
32060 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a UTF-16 bytes. .
32070 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 ** ^Any attempt
32080 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 to create a func
32090 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 tion with a long
320a0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 er name.** will
320b0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 result in [SQLIT
320c0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 E_MISUSE] being
320d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
320e0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
320f0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 eter (nArg).** i
32100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
32110 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 arguments that t
32120 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
32130 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 or.** aggregate
32140 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 takes. ^If this
32150 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c parameter is -1,
32160 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 then the SQL fu
32170 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 nction or.** agg
32180 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 regate may take
32190 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 any number of ar
321a0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 guments between
321b0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 0 and the limit.
321c0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 ** set by [sqlit
321d0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 e3_limit]([SQLIT
321e0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
321f0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 _ARG]). If the
32200 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
32210 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
32220 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 -1 or greater th
32230 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 an 127 then the
32240 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 behavior is.** u
32250 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
32260 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
32270 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c meter, eTextRep,
32280 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a specifies what.
32290 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
322a0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d | text encoding]
322b0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 this SQL functi
322c0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a on prefers for.*
322d0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 * its parameters
322e0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e . Every SQL fun
322f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
32300 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c tion must be abl
32310 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 e to work.** wit
32320 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c h UTF-8, UTF-16l
32330 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 e, or UTF-16be.
32340 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d But some implem
32350 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 entations may be
32360 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 .** more efficie
32370 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f nt with one enco
32380 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 ding than anothe
32390 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 r. ^An applicat
323a0 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b ion may.** invok
323b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 e sqlite3_create
323c0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 _function() or s
323d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
323e0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 nction16() multi
323f0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 ple.** times wit
32400 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 h the same funct
32410 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 ion but with dif
32420 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 ferent values of
32430 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 eTextRep..** ^W
32440 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 hen multiple imp
32450 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
32460 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
32470 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c n are available,
32480 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
32490 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 pick the one tha
324a0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c t involves the l
324b0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
324c0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a ata conversion..
324d0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f ** If there is o
324e0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 nly a single imp
324f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 lementation whic
32500 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 h does not care
32510 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 what text.** enc
32520 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 oding is used, t
32530 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 hen the fourth a
32540 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
32550 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a e [SQLITE_ANY]..
32560 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 **.** ^(The fift
32570 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
32580 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e n arbitrary poin
32590 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ter. The implem
325a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a entation of the.
325b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ** function can
325c0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 gain access to t
325d0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e his pointer usin
325e0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f g [sqlite3_user_
325f0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a data()].)^.**.**
32600 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 ^The sixth, sev
32610 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 enth and eighth
32620 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
32630 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
32640 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
32650 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
32660 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
32670 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
32680 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
32690 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 ** aggregate. ^A
326a0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
326b0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
326c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
326d0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 of the xFunc.**
326e0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e callback only; N
326f0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 ULL pointers mus
32700 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 t be passed as t
32710 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 he xStep and xFi
32720 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 nal.** parameter
32730 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 s. ^An aggregate
32740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
32750 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
32760 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
32770 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
32780 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 and NULL pointer
32790 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
327a0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 for xFunc. ^To d
327b0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e elete an existin
327c0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f g.** SQL functio
327d0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
327e0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 pass NULL pointe
327f0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 rs for all three
32800 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c function.** cal
32810 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 lbacks..**.** ^(
32820 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 If the ninth par
32830 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
32840 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
32850 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 n_v2() is not NU
32860 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 LL,.** then it i
32870 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 s destructor for
32880 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
32890 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a data pointer. .
328a0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f ** The destructo
328b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 r is invoked whe
328c0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 n the function i
328d0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 s deleted, eithe
328e0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 r by being.** ov
328f0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e erloaded or when
32900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
32910 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e nnection closes.
32920 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 )^.** ^The destr
32930 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e uctor is also in
32940 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c voked if the cal
32950 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
32960 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
32970 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e v2() fails..** ^
32980 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 When the destruc
32990 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 tor callback of
329a0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 the tenth parame
329b0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ter is invoked,
329c0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 it.** is passed
329d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
329e0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 t which is a cop
329f0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 y of the applica
32a00 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f tion data .** po
32a10 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 inter which was
32a20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 the fifth parame
32a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
32a40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
32a50 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 2()..**.** ^It i
32a60 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 s permitted to r
32a70 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 egister multiple
32a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
32a90 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
32aa0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 functions with t
32ab0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
32ac0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 with either dif
32ad0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f fering numbers o
32ae0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f f.** arguments o
32af0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 r differing pref
32b00 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
32b10 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 ings. ^SQLite w
32b20 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 ill use.** the i
32b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 mplementation th
32b40 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 at most closely
32b50 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 matches the way
32b60 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 in which the.**
32b70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
32b80 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 used. ^A functi
32b90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
32ba0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 n with a non-neg
32bb0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 ative.** nArg pa
32bc0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 rameter is a bet
32bd0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ter match than a
32be0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
32bf0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a entation with.**
32c00 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 a negative nArg
32c10 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 . ^A function w
32c20 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
32c30 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
32c40 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
32c50 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
32c60 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
32c70 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
32c80 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
32c90 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
32ca0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 ferent. .** ^A
32cb0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
32cc0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
32cd0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 erence is betwee
32ce0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 n UTF16le and UT
32cf0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c F16be.** is a cl
32d00 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 oser match than
32d10 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
32d20 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
32d30 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 fference is.** b
32d40 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 etween UTF8 and
32d50 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 UTF16..**.** ^Bu
32d60 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
32d70 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 may be overload
32d80 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 ed by new applic
32d90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
32da0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e nctions..**.** ^
32db0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 An application-d
32dc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
32dd0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
32de0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 call other.** SQ
32df0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e Lite interfaces.
32e00 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 However, such
32e10 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a calls must not.*
32e20 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 * close the data
32e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
32e40 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 nor finalize or
32e50 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
32e60 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
32e70 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e in which the fun
32e80 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
32e90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
32ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
32eb0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 te_function(. s
32ec0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
32ed0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 nst char *zFunct
32ee0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
32ef0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
32f00 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
32f10 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
32f20 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
32f30 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
32f40 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
32f50 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
32f60 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
32f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
32f80 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
32f90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
32fa0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 t*).);.SQLITE_AP
32fb0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
32fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
32fd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
32fe0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
32ff0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
33000 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
33010 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
33020 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
33030 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
33040 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
33050 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
33060 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
33070 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
33080 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
33090 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
330a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
330b0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 ntext*).);.SQLIT
330c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
330d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
330e0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 n_v2(. sqlite3
330f0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
33100 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
33110 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
33120 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
33130 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
33140 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
33150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
33160 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
33170 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
33180 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
33190 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
331a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
331b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
331c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 e3_context*),.
331d0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
331e0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*).);../*.**
331f0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
33200 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 Encodings.**.**
33210 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
33220 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
33230 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
33240 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
33250 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
33260 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
33270 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
33280 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
33290 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
332a0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
332b0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
332c0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
332d0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
332e0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
332f0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
33300 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
33310 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
33320 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
33330 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
33340 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
33350 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
33360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
33370 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
33380 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
33390 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
333a0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
333b0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
333c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
333d0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
333e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
333f0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
33400 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
33410 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
33420 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
33430 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
33440 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
33450 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
33460 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
33470 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
33480 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
33490 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
334a0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
334b0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
334c0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
334d0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
334e0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
334f0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
33500 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
33510 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a u what they do..
33520 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
33530 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 E_OMIT_DEPRECATE
33540 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c D.SQLITE_API SQL
33550 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
33560 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
33570 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
33580 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
33590 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
335a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
335b0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
335c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
335d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
335e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
335f0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 sqlite3_transfer
33600 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
33610 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 3_stmt*, sqlite3
33620 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
33630 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 API SQLITE_DEPRE
33640 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
33650 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 3_global_recover
33660 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
33670 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
33680 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 ATED void sqlite
33690 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
336a0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 (void);.SQLITE_A
336b0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
336c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
336d0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f _memory_alarm(vo
336e0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
336f0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 te3_int64,int),v
33700 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
33710 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
33720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
33730 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
33740 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
33750 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 lues.**.** The C
33760 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d -language implem
33770 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 entation of SQL
33780 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
33790 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a gregates uses.**
337a0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 this set of int
337b0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
337c0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 to access the pa
337d0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f rameter values o
337e0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f n.** the functio
337f0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a n or aggregate..
33800 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
33810 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
33820 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
33830 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
33840 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
33850 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
33860 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
33870 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
33880 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
33890 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
338a0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
338b0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
338c0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
338d0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
338e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
338f0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
33900 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
33910 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
33920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33930 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
33940 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
33950 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33960 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
33970 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
33980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
33990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
339a0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
339b0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
339c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
339d0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
339e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
339f0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
33a00 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
33a10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
33a20 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
33a30 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
33a40 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
33a50 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
33a60 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
33a70 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
33a80 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
33a90 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
33aa0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
33ab0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
33ac0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
33ad0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
33ae0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
33af0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 that these rout
33b00 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
33b10 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
33b20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
33b30 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
33b40 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
33b50 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
33b60 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
33b70 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
33b80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33b90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33ba0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
33bb0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
33bc0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
33bd0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
33be0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
33bf0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
33c00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
33c10 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
33c20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
33c30 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
33c40 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
33c50 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
33c60 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
33c70 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
33c80 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
33c90 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
33ca0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
33cb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
33cc0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
33cd0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
33ce0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
33cf0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
33d00 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
33d10 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
33d20 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
33d30 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
33d40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
33d50 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
33d60 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
33d70 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
33d80 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
33d90 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
33da0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
33db0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
33dc0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
33dd0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
33de0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
33df0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
33e00 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
33e10 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
33e20 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
33e30 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
33e40 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
33e50 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
33e60 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
33e70 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
33e80 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
33e90 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
33ea0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
33eb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
33ec0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
33ed0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
33ee0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
33ef0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
33f00 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
33f10 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
33f20 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
33f30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
33f40 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
33f50 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
33f60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
33f70 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
33f80 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
33f90 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
33fa0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
33fb0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
33fc0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
33fd0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
33fe0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
33ff0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
34000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
34010 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 arameters..*/.SQ
34020 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
34030 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
34040 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f ue_blob(sqlite3_
34050 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
34060 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
34070 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 value_bytes(sqli
34080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
34090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
340a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
340b0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
340c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f );.SQLITE_API do
340d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c uble sqlite3_val
340e0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 ue_double(sqlite
340f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34100 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
34110 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 3_value_int(sqli
34120 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
34130 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
34140 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 int64 sqlite3_va
34150 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 lue_int64(sqlite
34160 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34170 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 E_API const unsi
34180 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 gned char *sqlit
34190 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 e3_value_text(sq
341a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
341b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
341c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
341d0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 lue_text16(sqlit
341e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
341f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
34200 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
34210 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
34220 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
34230 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
34240 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
34250 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
34260 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34270 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
34280 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
34290 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
342a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
342b0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 te3_value_numeri
342c0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 c_type(sqlite3_v
342d0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 alue*);../*.** C
342e0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 API3REF: Obtain
342f0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 Aggregate Functi
34300 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a on Context.**.**
34310 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 Implementations
34320 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 of aggregate SQ
34330 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 L functions use
34340 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
34350 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
34360 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 ry for storing t
34370 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a heir state..**.*
34380 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d * ^The first tim
34390 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 e the sqlite3_ag
343a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
343b0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 C,N) routine is
343c0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 called .** for a
343d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 particular aggr
343e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 egate function,
343f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 SQLite.** alloca
34400 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c tes N of memory,
34410 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 zeroes out that
34420 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 memory, and ret
34430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a urns a pointer.*
34440 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d * to the new mem
34450 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 ory. ^On second
34460 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 and subsequent c
34470 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
34480 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
34490 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 text() for the s
344a0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 ame aggregate fu
344b0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c nction instance,
344c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 .** the same buf
344d0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e fer is returned.
344e0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 Sqlite3_aggreg
344f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 ate_context() is
34500 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c normally.** cal
34510 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 led once for eac
34520 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 h invocation of
34530 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 the xStep callba
34540 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a ck and then one.
34550 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 ** last time whe
34560 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c n the xFinal cal
34570 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
34580 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 . ^(When no row
34590 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 s match.** an ag
345a0 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 gregate query, t
345b0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 he xStep() callb
345c0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 ack of the aggre
345d0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a gate function.**
345e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
345f0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 is never called
34600 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 and xFinal() is
34610 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f called exactly o
34620 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 nce..** In those
34630 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f cases, sqlite3_
34640 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
34650 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c t() might be cal
34660 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 led for the.** f
34670 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 irst time from w
34680 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 ithin xFinal().)
34690 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
346a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
346b0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 ontext(C,N) rout
346c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 ine returns a NU
346d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 LL pointer if N
346e0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 is.** less than
346f0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
34700 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 or if a memory
34710 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f allocate error o
34720 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ccurs..**.** ^(T
34730 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 he amount of spa
34740 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ce allocated by
34750 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34760 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 e_context(C,N) i
34770 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 s.** determined
34780 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 by the N paramet
34790 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 er on first succ
347a0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 essful call. Ch
347b0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 anging the.** va
347c0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 lue of N in subs
347d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
347e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
347f0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 _context() withi
34800 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 n.** the same ag
34810 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
34820 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e instance will n
34830 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 ot resize the me
34840 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
34850 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c on.)^.**.** ^SQL
34860 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
34870 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f y frees the memo
34880 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ry allocated by
34890 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
348a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
348b0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 when the aggrega
348c0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 te query conclud
348d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
348e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 rst parameter mu
348f0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 st be a copy of
34900 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
34910 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
34920 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
34930 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
34940 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
34950 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 o the xStep or x
34960 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 Final callback r
34970 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
34980 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
34990 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gate.** function
349a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
349b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
349c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
349d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
349e0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
349f0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
34a00 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
34a10 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
34a20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
34a30 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 e_context(sqlite
34a40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
34a50 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nBytes);../*.**
34a60 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 CAPI3REF: User D
34a70 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ata For Function
34a80 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
34a90 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
34aa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
34ab0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
34ac0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
34ad0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
34ae0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
34af0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
34b00 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
34b10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
34b20 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
34b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
34b40 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
34b50 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
34b60 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
34b70 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
34b80 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
34b90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
34ba0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
34bb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
34bc0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
34bd0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c hich.** the appl
34be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34bf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
34c00 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
34c10 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
34c20 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 _user_data(sqlit
34c30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
34c40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
34c50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
34c60 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 on For Functions
34c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34c80 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
34c90 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 andle() interfac
34ca0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 e returns a copy
34cb0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 of.** the point
34cc0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 er to the [datab
34cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
34ce0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 (the 1st paramet
34cf0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
34d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
34d10 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
34d20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
34d30 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
34d40 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
34d50 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
34d60 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
34d70 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
34d80 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 nction..*/.SQLIT
34d90 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 E_API sqlite3 *s
34da0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
34db0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
34dc0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
34dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
34de0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 ction Auxiliary
34df0 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 Data.**.** The f
34e00 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e ollowing two fun
34e10 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 ctions may be us
34e20 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c ed by scalar SQL
34e30 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a functions to.**
34e40 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 associate metad
34e50 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e ata with argumen
34e60 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 t values. If the
34e70 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 same value is p
34e80 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 assed to.** mult
34e90 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 iple invocations
34ea0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c of the same SQL
34eb0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 function during
34ec0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e query execution
34ed0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 , under.** some
34ee0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 circumstances th
34ef0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 e associated met
34f00 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 adata may be pre
34f10 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 served. This may
34f20 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 .** be used, for
34f30 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 example, to add
34f40 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 a regular-expre
34f50 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 ssion matching s
34f60 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f calar.** functio
34f70 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 n. The compiled
34f80 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 version of the r
34f90 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f egular expressio
34fa0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a n is stored as.*
34fb0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 * metadata assoc
34fc0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 iated with the S
34fd0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 QL value passed
34fe0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 as the regular e
34ff0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 xpression.** pat
35000 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 tern. The compi
35010 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 led regular expr
35020 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 ession can be re
35030 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 used on multiple
35040 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
35050 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
35060 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 tion so that the
35070 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 original patter
35080 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 n string.** does
35090 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
350a0 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 recompiled on ea
350b0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a ch invocation..*
350c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
350d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
350e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
350f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
35100 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 he metadata.** a
35110 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 ssociated by the
35120 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
35130 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 data() function
35140 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 with the Nth arg
35150 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 ument.** value t
35160 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
35170 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
35180 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 on. ^If no metad
35190 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 ata has been eve
351a0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f r.** been set fo
351b0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 r the Nth argume
351c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 nt of the functi
351d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f on, or if the co
351e0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 rresponding.** f
351f0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
35200 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 r has changed si
35210 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 nce the meta-dat
35220 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 a was set,.** th
35230 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 en sqlite3_get_a
35240 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 uxdata() returns
35250 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
35260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
35270 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
35280 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 ) interface save
35290 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a s the metadata.*
352a0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
352b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
352c0 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 r as the metadat
352d0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a a for the N-th.*
352e0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 * argument of th
352f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
35300 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
35310 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 Subsequent.** c
35320 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
35330 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 get_auxdata() mi
35340 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 ght return this
35350 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a data, if it has.
35360 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 ** not been dest
35370 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 royed..** ^If it
35380 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
35390 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
353a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
353b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 ** function give
353c0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 n by the 4th par
353d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
353e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
353f0 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 on.** the metada
35400 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 ta when the corr
35410 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 esponding functi
35420 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 on parameter cha
35430 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 nges.** or when
35440 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
35450 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 t completes, whi
35460 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
35470 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 st..**.** SQLite
35480 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c is free to call
35490 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
354a0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 and drop metadat
354b0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 a on any.** para
354c0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e meter of any fun
354d0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d ction at any tim
354e0 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 e. ^The only gu
354f0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a arantee is that.
35500 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ** the destructo
35510 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 r will be called
35520 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 before the meta
35530 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e data is dropped.
35540 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 .**.** ^(In prac
35550 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
35560 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
35570 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
35580 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
35590 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
355a0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
355b0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
355c0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
355d0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 * values and [pa
355e0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a rameters].)^.**.
355f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
35600 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
35610 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
35620 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
35630 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
35640 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
35650 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
35660 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 d *sqlite3_get_a
35670 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
35680 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
35690 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
356a0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
356b0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
356c0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
356d0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
356e0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
356f0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
35700 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
35710 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
35720 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 ehavior.**.** Th
35730 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 ese are special
35740 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 values for the d
35750 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 estructor that i
35760 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 s passed in as t
35770 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 he.** final argu
35780 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 ment to routines
35790 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 like [sqlite3_r
357a0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 esult_blob()].
357b0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 ^If the destruct
357c0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
357d0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
357e0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
357f0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
35800 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
35810 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
35820 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
35830 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
35840 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 destroyed. ^Th
35850 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
35860 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
35870 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
35880 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
35890 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
358a0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
358b0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
358c0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
358d0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
358e0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
358f0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
35900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
35910 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
35920 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
35930 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
35940 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
35950 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ers. See ticket
35960 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 #2191..*/.typed
35970 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
35980 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
35990 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
359a0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
359b0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
359c0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
359d0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
359e0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
359f0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
35a00 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
35a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
35a20 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
35a30 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
35a40 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
35a50 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
35a60 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
35a70 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
35a80 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
35a90 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
35aa0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
35ab0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
35ac0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35ad0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
35ae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
35af0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
35b00 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
35b10 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
35b20 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
35b30 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
35b40 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 the [parameter
35b50 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 binding] family
35b60 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 of.** functions
35b70 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c used to bind val
35b80 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 ues to host para
35b90 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 meters in prepar
35ba0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a ed statements..*
35bb0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b * Refer to the [
35bc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 SQL parameter] d
35bd0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
35be0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
35bf0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e rmation..**.** ^
35c00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
35c10 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 lt_blob() interf
35c20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
35c30 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
35c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
35c50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
35c60 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 e the BLOB whose
35c70 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e content is poin
35c80 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 ted.** to by the
35c90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
35ca0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e r and which is N
35cb0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 bytes long wher
35cc0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 e N is the.** th
35cd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ird parameter..*
35ce0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35cf0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
35d00 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
35d10 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
35d20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
35d30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
35d40 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
35d50 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
35d60 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
35d70 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
35d80 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
35d90 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
35da0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
35db0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35dc0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
35dd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
35de0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
35df0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
35e00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
35e10 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
35e20 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
35e30 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
35e40 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
35e50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
35e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35e70 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
35e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
35e90 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
35ea0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
35eb0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
35ec0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
35ed0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c ception..** ^SQL
35ee0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 ite uses the str
35ef0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ing pointed to b
35f00 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 y the.** 2nd par
35f10 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
35f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
35f30 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
35f40 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
35f50 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 as the text of a
35f60 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
35f70 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 ^SQLite interp
35f80 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
35f90 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
35fa0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
35fb0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
35fc0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a UTF-8. ^SQLite.*
35fd0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
35fe0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
35ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36000 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
36010 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
36020 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 e order. ^If th
36030 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
36040 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
36050 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
36060 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
36070 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
36080 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
36090 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
360a0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
360b0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
360c0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
360d0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
360e0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
360f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
36100 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36110 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
36120 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
36130 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
36140 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
36150 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
36160 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
36170 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
36180 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
36190 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
361a0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 sage..** ^The sq
361b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
361c0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
361d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
361e0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
361f0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
36200 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
36210 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
36220 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
36230 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
36240 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
36250 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
36260 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
36270 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
36280 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
36290 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c arm..** ^The sql
362a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
362b0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f r_code() functio
362c0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 n changes the er
362d0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 ror code.** retu
362e0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 rned by SQLite a
362f0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e s a result of an
36300 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 error in a func
36310 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 tion. ^By defau
36320 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
36330 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
36340 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 ERROR. ^A subse
36350 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
36360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
36370 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
36380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
36390 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
363a0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
363b0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
363c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
363d0 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e sult_toobig() in
363e0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
363f0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
36400 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 n error.** indic
36410 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 ating that a str
36420 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 ing or BLOB is t
36430 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 oo long to repre
36440 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 sent..**.** ^The
36450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36460 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 nomem() interfac
36470 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
36480 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f to throw an erro
36490 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 r.** indicating
364a0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
364b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e location failed.
364c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
364d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
364e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
364f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
36500 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
36510 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
36520 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
36530 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 e 32-bit signed
36540 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
36550 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
36560 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e d argument..** ^
36570 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36580 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
36590 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
365a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
365b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
365c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
365d0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
365e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
365f0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
36600 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
36610 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
36620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36630 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
36640 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
36650 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
36660 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
36670 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
36680 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
36690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
366a0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
366b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
366c0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
366d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
366e0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
366f0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
36700 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
36710 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
36720 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
36730 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
36740 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
36750 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
36760 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
36770 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
36780 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
36790 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
367a0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
367b0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
367c0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
367d0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ely..** ^SQLite
367e0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 takes the text r
367f0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 esult from the a
36800 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a pplication from.
36810 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d ** the 2nd param
36820 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 eter of the sqli
36830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
36840 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
36850 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
36860 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
36870 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
36880 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
36890 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
368a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
368b0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
368c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
368d0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
368e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
368f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
36900 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
36910 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
36920 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
36930 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
36940 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
36950 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
36960 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
36970 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
36980 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
36990 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
369a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
369b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
369c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
369d0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 esult. If the 3
369e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
369f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
36a00 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 en it.** must be
36a10 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 the byte offset
36a20 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 into the string
36a30 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
36a40 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a erminator would.
36a50 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 ** appear if the
36a60 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 string where NU
36a70 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 L terminated. I
36a80 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
36a90 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ters occur.** in
36aa0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 the string at a
36ab0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 byte offset tha
36ac0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 t is less than t
36ad0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
36ae0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 3rd.** parameter
36af0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
36b00 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c ting string will
36b10 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
36b20 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a d NULs and the.*
36b30 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 * result of expr
36b40 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e essions operatin
36b50 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 g on strings wit
36b60 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
36b70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
36b80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
36b90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
36ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
36bb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
36bc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
36bd0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
36be0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
36bf0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
36c00 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
36c10 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
36c20 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
36c30 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
36c40 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
36c50 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
36c60 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
36c70 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
36c80 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
36c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
36ca0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
36cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
36cc0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
36cd0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
36ce0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
36cf0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
36d00 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
36d10 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
36d20 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
36d30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
36d40 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
36d50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
36d60 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
36d70 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
36d80 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
36d90 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
36da0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
36db0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
36dc0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
36dd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
36de0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
36df0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
36e00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
36e10 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
36e20 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
36e30 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
36e40 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
36e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
36e60 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
36e70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
36e80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
36e90 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
36ea0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
36eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36ec0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
36ed0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
36ee0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
36ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
36f00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
36f10 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
36f20 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
36f40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
36f50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
36f60 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
36f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
36f80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
36f90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
36fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
36fb0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
36fc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
36fd0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
36fe0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
36ff0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
37000 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
37010 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
37020 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
37030 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
37040 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
37050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
37060 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
37070 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
37080 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
37090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
370a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
370b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
370c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
370d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
370e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
370f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
37100 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
37110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
37120 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
37130 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
37140 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
37150 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
37160 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
37170 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37180 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
37190 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
371a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
371b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
371c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
371d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
371e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
371f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 t_blob(sqlite3_c
37200 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
37210 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
37220 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
37230 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
37240 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
37250 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
37260 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c t*, double);.SQL
37270 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
37280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37290 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
372a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
372b0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
372c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
372d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
372e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
372f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
37300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
37310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37320 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
37330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
37340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
37350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
37360 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
37370 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
37380 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
37390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
373a0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
373b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
373c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
373d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
373e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e _int(sqlite3_con
373f0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c text*, int);.SQL
37400 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
37410 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
37420 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
37430 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t*, sqlite3_int6
37440 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
37450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
37460 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f lt_null(sqlite3_
37470 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
37480 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
37490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
374a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
374b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
374c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
374d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
374e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
374f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
37500 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
37510 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
37520 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
37530 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
37540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
37550 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
37560 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
37570 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
37580 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
37590 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
375a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
375b0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
375c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
375d0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
375e0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
375f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
37600 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 esult_value(sqli
37610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
37620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
37630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
37640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
37650 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
37660 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
37670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37680 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
37690 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
376a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
376b0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
376c0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
376d0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
376e0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
376f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
37700 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
37710 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
37720 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
37730 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
37740 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
37750 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
37760 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
37770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
37780 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
37790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
377a0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
377b0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
377c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
377d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
377e0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
377f0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
37800 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
37810 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
37820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
37830 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
37840 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
37850 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
37860 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
37870 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
37880 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
37890 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
378a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
378b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
378c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
378d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
378e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
378f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
37900 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
37910 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
37920 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
37930 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
37940 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
37950 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
37960 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
37970 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
37980 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
37990 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
379a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
379b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
379c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
379d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
379e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
379f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
37a00 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
37a10 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
37a20 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
37a30 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
37a40 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
37a50 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
37a60 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
37a70 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
37a80 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
37a90 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
37aa0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
37ab0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
37ac0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
37ad0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
37ae0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
37af0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
37b00 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
37b10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
37b20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
37b30 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
37b40 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
37b50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
37b60 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
37b70 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
37b80 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
37b90 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
37ba0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
37bb0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
37bc0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
37bd0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
37be0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
37bf0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
37c00 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
37c10 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
37c20 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
37c30 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
37c40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
37c50 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
37c60 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
37c70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
37c80 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
37c90 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
37ca0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
37cb0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
37cc0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
37cd0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
37ce0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
37cf0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
37d00 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
37d10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
37d20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
37d30 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
37d40 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
37d50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
37d60 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
37d70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
37d80 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
37d90 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
37da0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
37db0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
37dc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
37dd0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
37de0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
37df0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
37e00 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
37e10 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
37e20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
37e30 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
37e40 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
37e50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
37e60 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
37e70 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
37e80 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
37e90 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
37ea0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
37eb0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
37ec0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
37ed0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
37ee0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
37ef0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
37f00 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
37f10 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
37f20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
37f30 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
37f40 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
37f50 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
37f60 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
37f70 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
37f80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
37f90 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
37fa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
37fb0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
37fc0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
37fd0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
37fe0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
37ff0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
38000 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
38010 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
38020 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
38030 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
38040 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
38050 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
38060 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
38070 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
38080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
38090 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
380a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
380b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
380c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
380d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
380e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
380f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
38100 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
38110 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
38120 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
38130 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
38140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
38150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
38160 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
38170 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
38180 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
38190 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
381a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
381b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
381c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
381d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
381e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
381f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
38200 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
38210 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
38220 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
38230 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
38240 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
38250 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
38260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
38270 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
38280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
38290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
382a0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
382b0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
382c0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
382d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
382e0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
382f0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
38300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
38310 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
38320 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
38330 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
38340 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
38350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
38360 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
38370 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
38380 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
38390 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
383a0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
383b0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
383c0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
383d0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
383e0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
383f0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
38400 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
38410 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
38420 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
38430 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
38440 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
38450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
38460 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
38470 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
38480 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
38490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
384a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
384b0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
384c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
384d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
384e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
384f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
38500 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
38510 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
38520 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
38530 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
38540 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e void *pArg,. in
38550 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
38560 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
38570 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
38580 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 d*).);.SQLITE_AP
38590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
385a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
385b0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
385c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
385d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
385e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
385f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
38600 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
38610 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
38620 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 const void*),.
38630 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
38640 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 void*).);.SQLITE
38650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
38660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
38670 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
38680 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a . const void *
38690 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 zName,. int eTe
386a0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
386b0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
386c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
386d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
386e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
386f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
38700 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 : Collation Need
38710 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ed Callbacks.**.
38720 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 ** ^To avoid hav
38730 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
38740 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
38750 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
38760 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
38770 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
38780 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
38790 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
387a0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
387b0 2a 2a 20 5b 64 61 74 61 62 6