System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact ece5a2fd4397f98c2d4c451444e26f1ea4e2a8a0:


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 37 2e 20 20 42  ersion 3.7.7.  B
00b0: 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c 20  y combining all 
00c0: 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 43  the individual C
00d0: 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 6f   code files into
00e0: 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c 65   this .** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74 68   not have .** th
0310: 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65  e "sqlite3.h" he
0320: 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e  ader file at han
0330: 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64  d, you will find
0340: 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64   a copy embedded
0350: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74   within.** the t
0360: 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ext of this file
0370: 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42  .  Search for "B
0380: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
0390: 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65  3.h" to find the
03a0: 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65   start.** of the
03b0: 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65   embedded sqlite
03c0: 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e  3.h header file.
03d0: 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64  ) Additional cod
03e0: 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e  e files may be n
03f0: 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20  eeded.** if you 
0400: 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74  want a wrapper t
0410: 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69  o interface SQLi
0420: 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f  te with your cho
0430: 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69  ice of programmi
0440: 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20  ng.** language. 
0450: 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65  The code for the
0460: 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61   "sqlite3" comma
0470: 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73  nd-line shell is
0480: 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65   also in a.** se
0490: 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69  parate file. Thi
04a0: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20  s file contains 
04b0: 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68  only code for th
04c0: 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69  e core SQLite li
04d0: 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e  brary..*/.#defin
04e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a  e SQLITE_CORE 1.
04f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
0500: 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69  MALGAMATION 1.#i
0510: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49  fndef SQLITE_PRI
0520: 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51  VATE.# define SQ
0530: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61  LITE_PRIVATE sta
0540: 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  tic.#endif.#ifnd
0550: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
0560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
0570: 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a 2a  I.#endif./******
0580: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
0590: 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 20  ile sqliteInt.h 
05a0: 2a 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 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
05d0: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
05e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
05f0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0600: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0610: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0620: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0630: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0640: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0650: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0660: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0670: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
0680: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
0690: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
06a0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
06b0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
06c0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
06d0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
06e0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
06f0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
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 0a  ***************.
0740: 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 65  ** Internal inte
0750: 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f 6e  rface definition
0760: 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a 2a  s for SQLite..**
0770: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
0780: 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69 6e  ITEINT_H_.#defin
0790: 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a  e _SQLITEINT_H_.
07a0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65  ./*.** These #de
07b0: 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61  fines should ena
07c0: 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75  ble >2GB file su
07d0: 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69  pport on POSIX i
07e0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
07f0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
0800: 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74  stem supports it
0810: 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63  .  If the OS lac
0820: 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65  ks.** large file
0830: 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20   support, or if 
0840: 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77  the OS is window
0850: 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20  s, these should 
0860: 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
0870: 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20   Ticket #2739:  
0880: 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53  The _LARGEFILE_S
0890: 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74  OURCE macro must
08a0: 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20 61   appear before a
08b0: 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e  ny.** system #in
08c0: 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20  cludes.  Hence, 
08d0: 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f  this block of co
08e0: 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20 76  de must be the v
08f0: 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64  ery first.** cod
0900: 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20  e in all source 
0910: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72  files..**.** Lar
0920: 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20  ge file support 
0930: 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20  can be disabled 
0940: 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49  using the -DSQLI
0950: 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73  TE_DISABLE_LFS s
0960: 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20  witch.** on the 
0970: 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64  compiler command
0980: 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20   line.  This is 
0990: 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f 75  necessary if you
09a0: 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a   are compiling.*
09b0: 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61  * on a recent ma
09c0: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48  chine (ex: Red H
09d0: 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20  at 7.2) but you 
09e0: 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74  want your code t
09f0: 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20  o work.** on an 
0a00: 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65  older machine (e
0a10: 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e  x: Red Hat 6.0).
0a20: 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65    If you compile
0a30: 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a   on Red Hat 7.2.
0a40: 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73 20  ** without this 
0a50: 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65  option, LFS is e
0a60: 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20  nable.  But LFS 
0a70: 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69  does not exist i
0a80: 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20  n the kernel.** 
0a90: 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20  in Red Hat 6.0, 
0aa0: 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27  so the code won'
0ab0: 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20  t work.  Hence, 
0ac0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61  for maximum bina
0ad0: 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74  ry.** portabilit
0ae0: 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69  y you should omi
0af0: 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d  t LFS..**.** Sim
0b00: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72  ilar is true for
0b10: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20   Mac OS X.  LFS 
0b20: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65  is only supporte
0b30: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20  d on Mac OS X 9 
0b40: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69  and later..*/.#i
0b50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53  fndef SQLITE_DIS
0b60: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e  ABLE_LFS.# defin
0b70: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20  e _LARGE_FILE   
0b80: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f      1.# ifndef _
0b90: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53  FILE_OFFSET_BITS
0ba0: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c  .#   define _FIL
0bb0: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34  E_OFFSET_BITS 64
0bc0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e  .# endif.# defin
0bd0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55  e _LARGEFILE_SOU
0be0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a  RCE 1.#endif../*
0bf0: 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 20  .** Include the 
0c00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68 65  configuration he
0c10: 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20 27  ader output by '
0c20: 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77 65  configure' if we
0c30: 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  're using the.**
0c40: 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64 20   autoconf-based 
0c50: 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66 20  build.*/.#ifdef 
0c60: 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f 4e  _HAVE_SQLITE_CON
0c70: 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20 22  FIG_H.#include "
0c80: 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69 66  config.h".#endif
0c90: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
0ca0: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
0cb0: 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20 6d  Limit.h in the m
0cc0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
0cd0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
0ce0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
0cf0: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
0d00: 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a 2a  iteLimit.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: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61 79  /./*.** 2007 May
0d40: 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74   7.**.** The aut
0d50: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
0d60: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
0d70: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
0d80: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
0d90: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
0da0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
0db0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
0dc0: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
0dd0: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
0de0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
0df0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
0e00: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
0e10: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
0e20: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
0e30: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
0e40: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
0e50: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
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 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66 69  *.** .** This fi
0eb0: 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69 6f  le defines vario
0ec0: 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68 61  us limits of wha
0ed0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72 6f  t SQLite can pro
0ee0: 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  cess..*/../*.** 
0ef0: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
0f00: 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72 20  th of a TEXT or 
0f10: 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20 20  BLOB in bytes.  
0f20: 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c 69   This also.** li
0f30: 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
0f40: 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62 6c   a row in a tabl
0f50: 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a 2a  e or index..**.*
0f60: 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69 74  * The hard limit
0f70: 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79 20   is the ability 
0f80: 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
0f90: 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74 6f  ed integer.** to
0fa0: 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65 3a   count the size:
0fb0: 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37 34   2^31-1 or 21474
0fc0: 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64 65  83647..*/.#ifnde
0fd0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e  f SQLITE_MAX_LEN
0fe0: 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  GTH.# define SQL
0ff0: 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20 31  ITE_MAX_LENGTH 1
1000: 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69 66  000000000.#endif
1010: 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  ../*.** This is 
1020: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1030: 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20 2a  er of.**.**    *
1040: 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   Columns in a ta
1050: 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75  ble.**    * Colu
1060: 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1070: 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73 20  **    * Columns 
1080: 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20 20  in a view.**    
1090: 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20 53  * Terms in the S
10a0: 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e 20  ET clause of an 
10b0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10c0: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
10d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
10e0: 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
10f0: 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20 54  tement.**    * T
1100: 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f 55  erms in the GROU
1110: 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42 59  P BY or ORDER BY
1120: 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53 45   clauses of a SE
1130: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1140: 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69 6e  **    * Terms in
1150: 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61 75   the VALUES clau
1160: 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54 20  se of an INSERT 
1170: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
1180: 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  The hard upper l
1190: 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32 36  imit here is 326
11a0: 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62 61  76.  Most databa
11b0: 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a 2a  se people will.*
11c0: 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74 20  * tell you that 
11d0: 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61 6c  in a well-normal
11e0: 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20 79  ized database, y
11f0: 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75 6c  ou usually shoul
1200: 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d 6f  d.** not have mo
1210: 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e 20  re than a dozen 
1220: 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69 6e  or so columns in
1230: 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e 64   any table.  And
1240: 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20 74   if.** that is t
1250: 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20 69  he case, there i
1260: 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68 61  s no point in ha
1270: 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 61  ving more than a
1280: 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76 61   few.** dozen va
1290: 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20 74  lues in any of t
12a0: 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74 69  he other situati
12b0: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62  ons described ab
12c0: 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ove..*/.#ifndef 
12d0: 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d  SQLITE_MAX_COLUM
12e0: 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  N.# define SQLIT
12f0: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30 30  E_MAX_COLUMN 200
1300: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1310: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1320: 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 53  th of a single S
1330: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1340: 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  bytes..**.** It 
1350: 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20 63  used to be the c
1360: 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e 67  ase that setting
1370: 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20 7a   this value to z
1380: 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75 72  ero would.** tur
1390: 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66 2e  n the limit off.
13a0: 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f 6e    That is no lon
13b0: 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69 73  ger true.  It is
13c0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a 2a   not possible.**
13d0: 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c 69   to turn this li
13e0: 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66 6e  mit off..*/.#ifn
13f0: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  def SQLITE_MAX_S
1400: 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66 69  QL_LENGTH.# defi
1410: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51  ne SQLITE_MAX_SQ
1420: 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30 30  L_LENGTH 1000000
1430: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1440: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  * The maximum de
1450: 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65 73  pth of an expres
1460: 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73 20  sion tree. This 
1470: 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a 2a  is limited to .*
1480: 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62 79  * some extent by
1490: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f   SQLITE_MAX_SQL_
14a0: 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d 65  LENGTH. But some
14b0: 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20 0a  time you might .
14c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63 65  ** want to place
14d0: 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69 6d   more severe lim
14e0: 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 6c  its on the compl
14f0: 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a 20  exity of an .** 
1500: 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a 2a  expression..**.*
1510: 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 75  * A value of 0 u
1520: 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61 74  sed to mean that
1530: 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 6e   the limit was n
1540: 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a 20  ot enforced..** 
1550: 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20 6c  But that is no l
1560: 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68 65  onger true.  The
1570: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73 74   limit is now st
1580: 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64 0a  rictly enforced.
1590: 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73 2e  ** at all times.
15a0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
15b0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15c0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
15d0: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48  E_MAX_EXPR_DEPTH
15e0: 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a   1000.#endif../*
15f0: 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20  .** The maximum 
1600: 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1610: 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1620: 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
1630: 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e 65  ** The code gene
1640: 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f 75  rator for compou
1650: 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1660: 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a 2a  ents does one.**
1670: 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72 73   level of recurs
1680: 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65 72  ion for each ter
1690: 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65 72  m.  A stack over
16a0: 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74 0a  flow can result.
16b0: 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65 72  ** if the number
16c0: 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f 6f   of terms is too
16d0: 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61 63   large.  In prac
16e0: 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a 2a  tice, most SQL.*
16f0: 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72 65  * never has more
1700: 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65 72   than 3 or 4 ter
1710: 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75 65  ms.  Use a value
1720: 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c 65   of 0 to disable
1730: 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f 6e  .** any limit on
1740: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1750: 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1760: 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23 69  nt SELECT..*/.#i
1770: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1780: 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1790: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
17a0: 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  _MAX_COMPOUND_SE
17b0: 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66 0a  LECT 500.#endif.
17c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d  ./*.** The maxim
17d0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70 63  um number of opc
17e0: 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20 70  odes in a VDBE p
17f0: 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20 63  rogram..** Not c
1800: 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63 65  urrently enforce
1810: 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  d..*/.#ifndef SQ
1820: 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50  LITE_MAX_VDBE_OP
1830: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1840: 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35 30  _MAX_VDBE_OP 250
1850: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1860: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1870: 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1880: 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   to an SQL funct
1890: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ion..*/.#ifndef 
18a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54  SQLITE_MAX_FUNCT
18b0: 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e 65  ION_ARG.# define
18c0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18d0: 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65 6e  TION_ARG 127.#en
18e0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d  dif../*.** The m
18f0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1900: 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65 73   in-memory pages
1910: 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65 20   to use for the 
1920: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  main database.**
1930: 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20 74   table and for t
1940: 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73 2e  emporary tables.
1950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46    The SQLITE_DEF
1960: 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a  AULT_CACHE_SIZE.
1970: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1980: 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f  E_DEFAULT_CACHE_
1990: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
19a0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43  LITE_DEFAULT_CAC
19b0: 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23 65  HE_SIZE  2000.#e
19c0: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
19d0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d 50  ITE_DEFAULT_TEMP
19e0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64 65  _CACHE_SIZE.# de
19f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1a00: 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f 53  ULT_TEMP_CACHE_S
1a10: 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66 0a  IZE  500.#endif.
1a20: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  ./*.** The defau
1a30: 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72 61  lt number of fra
1a40: 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  mes to accumulat
1a50: 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69 6c  e in the log fil
1a60: 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65 63  e before.** chec
1a70: 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64 61  kpointing the da
1a80: 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f  tabase in WAL mo
1a90: 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  de..*/.#ifndef S
1aa0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41  QLITE_DEFAULT_WA
1ab0: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54  L_AUTOCHECKPOINT
1ac0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1ad0: 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55 54  _DEFAULT_WAL_AUT
1ae0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30 30  OCHECKPOINT  100
1af0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  0.#endif../*.** 
1b00: 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b10: 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
1b20: 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73 20  atabases.  This 
1b30: 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1b40: 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54 68  0.** and 62.  Th
1b50: 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  e upper bound on
1b60: 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20 61   62 is because a
1b70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1b80: 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73 65  bitmap.** is use
1b90: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
1ba0: 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20 64  track attached d
1bb0: 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69 66  atabases..*/.#if
1bc0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1bd0: 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69 6e  ATTACHED.# defin
1be0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54  e SQLITE_MAX_ATT
1bf0: 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66 0a  ACHED 10.#endif.
1c00: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
1c10: 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20 3f  mum value of a ?
1c20: 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68 61  nnn wildcard tha
1c30: 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69 6c  t the parser wil
1c40: 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69 66  l accept..*/.#if
1c50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1c60: 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
1c70: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
1c80: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
1c90: 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a 0a  BER 999.#endif..
1ca0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65 20  /* Maximum page 
1cb0: 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65 72  size.  The upper
1cc0: 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20 76   bound on this v
1cd0: 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20 20  alue is 65536.  
1ce0: 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a 20  This a limit.** 
1cf0: 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20 75  imposed by the u
1d00: 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66 66  se of 16-bit off
1d10: 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63 68  sets within each
1d20: 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61 72   page..**.** Ear
1d30: 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  lier versions of
1d40: 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64 20   SQLite allowed 
1d50: 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61 6e  the user to chan
1d60: 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61 74  ge this value at
1d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1d80: 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f 6e  . This is no lon
1d90: 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20 6f  ger permitted, o
1da0: 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74 68  n the grounds th
1db0: 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a 2a  at it creates.**
1dc0: 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74 20   a library that 
1dd0: 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20 69  is technically i
1de0: 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68  ncompatible with
1df0: 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72 61   an SQLite libra
1e00: 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  ry .** compiled 
1e10: 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e 74  with a different
1e20: 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72 6f   limit. If a pro
1e30: 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  cess operating o
1e40: 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  n a database .**
1e50: 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69 7a   with a page-siz
1e60: 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65 73  e of 65536 bytes
1e70: 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20 61   crashes, then a
1e80: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53 51  n instance of SQ
1e90: 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  Lite .** compile
1ea0: 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  d with the defau
1eb0: 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69 6d  lt page-size lim
1ec0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 61  it will not be a
1ed0: 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b 20  ble to rollback 
1ee0: 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64 20  .** the aborted 
1ef0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
1f00: 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f 20  s could lead to 
1f10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
1f20: 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ion..*/.#ifdef S
1f30: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
1f40: 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  IZE.# undef SQLI
1f50: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45  TE_MAX_PAGE_SIZE
1f60: 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
1f70: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f80: 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a 0a  SIZE 65536.../*.
1f90: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  ** The default s
1fa0: 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ize of a databas
1fb0: 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e 64  e page..*/.#ifnd
1fc0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  ef SQLITE_DEFAUL
1fd0: 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64 65  T_PAGE_SIZE.# de
1fe0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46 41  fine SQLITE_DEFA
1ff0: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31 30  ULT_PAGE_SIZE 10
2000: 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  24.#endif.#if SQ
2010: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2020: 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d 41  E_SIZE>SQLITE_MA
2030: 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75 6e  X_PAGE_SIZE.# un
2040: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
2050: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
2060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
2070: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 53  AULT_PAGE_SIZE S
2080: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53  QLITE_MAX_PAGE_S
2090: 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  IZE.#endif../*.*
20a0: 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69 66  * Ordinarily, if
20b0: 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78 70   no value is exp
20c0: 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65 64  licitly provided
20d0: 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 73  , SQLite creates
20e0: 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77 69   databases.** wi
20f0: 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51 4c  th page size SQL
2100: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45  ITE_DEFAULT_PAGE
2110: 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c 20  _SIZE. However, 
2120: 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69 6e  based on certain
2130: 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72 61  .** device chara
2140: 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63 74  cteristics (sect
2150: 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f 6d  or-size and atom
2160: 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70 6f  ic write() suppo
2170: 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  rt),.** SQLite m
2180: 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72 67  ay choose a larg
2190: 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20 63  er value. This c
21a0: 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20 6d  onstant is the m
21b0: 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a 20  aximum value.** 
21c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f 6f  SQLite will choo
21d0: 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a 2a  se on its own..*
21e0: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
21f0: 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47  _MAX_DEFAULT_PAG
2200: 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20  E_SIZE.# define 
2210: 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55  SQLITE_MAX_DEFAU
2220: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31 39  LT_PAGE_SIZE 819
2230: 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c  2.#endif.#if SQL
2240: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
2250: 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45  PAGE_SIZE>SQLITE
2260: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
2270: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41   undef SQLITE_MA
2280: 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53  X_DEFAULT_PAGE_S
2290: 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  IZE.# define SQL
22a0: 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f  ITE_MAX_DEFAULT_
22b0: 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54 45  PAGE_SIZE SQLITE
22c0: 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23  _MAX_PAGE_SIZE.#
22d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d 61  endif.../*.** Ma
22e0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
22f0: 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61 74  pages in one dat
2300: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
2310: 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c 79  * This is really
2320: 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75 6c   just the defaul
2330: 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
2340: 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 70  max_page_count p
2350: 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20 76  ragma..** This v
2360: 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77 65  alue can be lowe
2370: 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29 20  red (or raised) 
2380: 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2390: 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d 61  g that the.** ma
23a0: 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61 63  x_page_count mac
23b0: 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ro..*/.#ifndef S
23c0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23d0: 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53 51  OUNT.# define SQ
23e0: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f  LITE_MAX_PAGE_CO
23f0: 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a 23  UNT 1073741823.#
2400: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78  endif../*.** Max
2410: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e 20  imum length (in 
2420: 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70 61  bytes) of the pa
2430: 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45 20  ttern in a LIKE 
2440: 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72 61  or GLOB.** opera
2450: 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  tor..*/.#ifndef 
2460: 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f  SQLITE_MAX_LIKE_
2470: 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a 23  PATTERN_LENGTH.#
2480: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d   define SQLITE_M
2490: 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  AX_LIKE_PATTERN_
24a0: 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65 6e  LENGTH 50000.#en
24b0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69 6d  dif../*.** Maxim
24c0: 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24d0: 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c 75  rs..**.** A valu
24f0: 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68 61  e of 1 means tha
2500: 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  t a trigger prog
2510: 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  ram will not be 
2520: 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a 2a  able to itself.*
2530: 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67 67  * fire any trigg
2540: 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66 20  ers. A value of 
2550: 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20  0 means that no 
2560: 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
2570: 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79 20   at all .** may 
2580: 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f 0a  be executed..*/.
2590: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
25a0: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  AX_TRIGGER_DEPTH
25b0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
25c0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50  _MAX_TRIGGER_DEP
25d0: 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a  TH 1000.#endif..
25e0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
25f0: 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69 6d  End of sqliteLim
2600: 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  it.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 2f 0a  **************/.
2630: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  /************** 
2640: 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65  Continuing where
2650: 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20   we left off in 
2660: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a  sqliteInt.h ****
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  **************/.
2680: 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69 73  ./* Disable nuis
2690: 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e  ance warnings on
26a0: 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c 65   Borland compile
26b0: 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  rs */.#if define
26c0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
26d0: 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72 63  #pragma warn -rc
26e0: 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c 65  h /* unreachable
26f0: 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d 61   code */.#pragma
2700: 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43 6f   warn -ccc /* Co
2710: 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61 79  ndition is alway
2720: 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65 20  s true or false 
2730: 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20  */.#pragma warn 
2740: 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65 64  -aus /* Assigned
2750: 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72 20   value is never 
2760: 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61 20  used */.#pragma 
2770: 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f 6d  warn -csu /* Com
2780: 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61 6e  paring signed an
2790: 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23 70  d unsigned */.#p
27a0: 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61 20  ragma warn -spa 
27b0: 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70 6f  /* Suspicious po
27c0: 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69 63  inter arithmetic
27d0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e   */.#endif../* N
27e0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75  eeded for variou
27f0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e  s definitions...
2800: 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e 55   */.#ifndef _GNU
2810: 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e 65  _SOURCE.# define
2820: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e   _GNU_SOURCE.#en
2830: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75  dif../*.** Inclu
2840: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64  de standard head
2850: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65  er files as nece
2860: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20  ssary.*/.#ifdef 
2870: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69  HAVE_STDINT_H.#i
2880: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68  nclude <stdint.h
2890: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  >.#endif.#ifdef 
28a0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a  HAVE_INTTYPES_H.
28b0: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70  #include <inttyp
28c0: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es.h>.#endif../*
28d0: 0a 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  .** The number o
28e0: 66 20 73 61 6d 70 6c 65 73 20 6f 66 20 61 6e 20  f samples of an 
28f0: 69 6e 64 65 78 20 74 68 61 74 20 53 51 4c 69 74  index that SQLit
2900: 65 20 74 61 6b 65 73 20 69 6e 20 6f 72 64 65 72  e takes in order
2910: 20 74 6f 20 0a 2a 2a 20 63 6f 6e 73 74 72 75 63   to .** construc
2920: 74 20 61 20 68 69 73 74 6f 67 72 61 6d 20 6f 66  t a histogram of
2930: 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
2940: 6e 74 20 77 68 65 6e 20 72 75 6e 6e 69 6e 67 20  nt when running 
2950: 41 4e 41 4c 59 5a 45 0a 2a 2a 20 61 6e 64 20 77  ANALYZE.** and w
2960: 69 74 68 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ith SQLITE_ENABL
2970: 45 5f 53 54 41 54 32 0a 2a 2f 0a 23 64 65 66 69  E_STAT2.*/.#defi
2980: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
2990: 53 41 4d 50 4c 45 53 20 31 30 0a 0a 2f 2a 0a 2a  SAMPLES 10../*.*
29a0: 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
29b0: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
29c0: 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65 72 73  to cast pointers
29d0: 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61 6e 64   to integers and
29e0: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74 6f 20  .** integers to 
29f0: 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65 20 77  pointers.  The w
2a00: 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73 20 76  ay you do this v
2a10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 63  aries from one c
2a20: 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20 74 68  ompiler.** to th
2a30: 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20 68 61  e next, so we ha
2a40: 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74 68 65  ve developed the
2a50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74 20 6f   following set o
2a60: 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e 74 73  f #if statements
2a70: 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74 65 20  .** to generate 
2a80: 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61 63 72  appropriate macr
2a90: 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20 72 61  os for a wide ra
2aa0: 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65 72 73  nge of compilers
2ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 72 72  ..**.** The corr
2ac0: 65 63 74 20 22 41 4e 53 49 22 20 77 61 79 20 74  ect "ANSI" way t
2ad0: 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74 6f 20  o do this is to 
2ae0: 75 73 65 20 74 68 65 20 69 6e 74 70 74 72 5f 74  use the intptr_t
2af0: 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66 6f 72   type. .** Unfor
2b00: 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74 20 74  tunately, that t
2b10: 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20 61 76  ypedef is not av
2b20: 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c 20 63  ailable on all c
2b30: 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a 2a 20  ompilers, or.** 
2b40: 69 66 20 69 74 20 69 73 20 61 76 61 69 6c 61 62  if it is availab
2b50: 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65 73 20  le, it requires 
2b60: 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66 20 73  an #include of s
2b70: 70 65 63 69 66 69 63 20 68 65 61 64 65 72 73 0a  pecific headers.
2b80: 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66 72 6f  ** that vary fro
2b90: 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20 74 6f  m one machine to
2ba0: 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a   the next..**.**
2bb0: 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a 20 20   Ticket #3860:  
2bc0: 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34 2e 32  The llvm-gcc-4.2
2bd0: 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d 20 41   compiler from A
2be0: 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e 0a 2a  pple chokes on.*
2bf0: 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29 26 28  * the ((void*)&(
2c00: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20 63 6f  (char*)0)[X]) co
2c10: 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20 4d 53  nstruct.  But MS
2c20: 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28 28 76  VC chokes on ((v
2c30: 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20 53 6f  oid*)(X))..** So
2c40: 20 77 65 20 68 61 76 65 20 74 6f 20 64 65 66 69   we have to defi
2c50: 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ne the macros in
2c60: 20 64 69 66 66 65 72 65 6e 74 20 77 61 79 73 20   different ways 
2c70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2c80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a 2a 2f  .** compiler..*/
2c90: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 50  .#if defined(__P
2ca0: 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 20 20  TRDIFF_TYPE__)  
2cb0: 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73 68 6f  /* This case sho
2cc0: 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47 43 43  uld work for GCC
2cd0: 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51 4c   */.# define SQL
2ce0: 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58  ITE_INT_TO_PTR(X
2cf0: 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f 50 54  )  ((void*)(__PT
2d00: 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29  RDIFF_TYPE__)(X)
2d10: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
2d20: 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20  E_PTR_TO_INT(X) 
2d30: 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44 49 46   ((int)(__PTRDIF
2d40: 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a 23 65  F_TYPE__)(X)).#e
2d50: 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f 5f 47  lif !defined(__G
2d60: 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f 2a 20  NUC__)       /* 
2d70: 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70 69 6c  Works for compil
2d80: 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e 20 4c  ers other than L
2d90: 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  LVM */.# define 
2da0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2db0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 26 28  R(X)  ((void*)&(
2dc0: 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a 23 20  (char*)0)[X]).# 
2dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2de0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2df0: 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29 2d 28  nt)(((char*)X)-(
2e00: 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69 66 20  char*)0)).#elif 
2e10: 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53 54 44  defined(HAVE_STD
2e20: 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73 65 20  INT_H)   /* Use 
2e30: 74 68 69 73 20 63 61 73 65 20 69 66 20 77 65 20  this case if we 
2e40: 68 61 76 65 20 41 4e 53 49 20 68 65 61 64 65 72  have ANSI header
2e50: 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53 51  s */.# define SQ
2e60: 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52 28  LITE_INT_TO_PTR(
2e70: 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69 6e 74  X)  ((void*)(int
2e80: 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64 65 66  ptr_t)(X)).# def
2e90: 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54  ine SQLITE_PTR_T
2ea0: 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29  O_INT(X)  ((int)
2eb0: 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23  (intptr_t)(X)).#
2ec0: 65 6c 73 65 20 20 20 20 20 20 20 20 20 20 20 20  else            
2ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2ee0: 20 47 65 6e 65 72 61 74 65 73 20 61 20 77 61 72   Generates a war
2ef0: 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20 61 6c  ning - but it al
2f00: 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a 23 20  ways works */.# 
2f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2f20: 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28 28 76  T_TO_PTR(X)  ((v
2f30: 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65 66 69  oid*)(X)).# defi
2f40: 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f 54 4f  ne SQLITE_PTR_TO
2f50: 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74 29 28  _INT(X)  ((int)(
2f60: 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  X)).#endif../*.*
2f70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54 48 52  * The SQLITE_THR
2f80: 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20 6d 75  EADSAFE macro mu
2f90: 73 74 20 62 65 20 64 65 66 69 6e 65 64 20 61 73  st be defined as
2fa0: 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a 2a 20   0, 1, or 2..** 
2fb0: 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65 73 20  0 means mutexes 
2fc0: 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c 79 20  are permanently 
2fd0: 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68 65 20  disable and the 
2fe0: 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76 65 72  library is never
2ff0: 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65 2e 20  .** threadsafe. 
3000: 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c 69 62   1 means the lib
3010: 72 61 72 79 20 69 73 20 73 65 72 69 61 6c 69 7a  rary is serializ
3020: 65 64 20 77 68 69 63 68 20 69 73 20 74 68 65 20  ed which is the 
3030: 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76 65 6c  highest.** level
3040: 20 6f 66 20 74 68 72 65 61 64 73 61 66 65 74 79   of threadsafety
3050: 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  2 means the l
3060: 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69 74 68  ibary is multith
3070: 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69 70 6c  readed - multipl
3080: 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63 61 6e  e.** threads can
3090: 20 75 73 65 20 53 51 4c 69 74 65 20 61 73 20 6c   use SQLite as l
30a0: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
30b0: 72 65 61 64 73 20 74 72 79 20 74 6f 20 75 73 65  reads try to use
30c0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
30d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
30f0: 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72 20 76  e..**.** Older v
3100: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3110: 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69 6f 6e  e used an option
3120: 61 6c 20 54 48 52 45 41 44 53 41 46 45 20 6d 61  al THREADSAFE ma
3130: 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70 70 6f  cro..** We suppo
3140: 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65 67 61  rt that for lega
3150: 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  cy..*/.#if !defi
3160: 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 45 41  ned(SQLITE_THREA
3170: 44 53 41 46 45 29 0a 23 69 66 20 64 65 66 69 6e  DSAFE).#if defin
3180: 65 64 28 54 48 52 45 41 44 53 41 46 45 29 0a 23  ed(THREADSAFE).#
3190: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
31a0: 48 52 45 41 44 53 41 46 45 20 54 48 52 45 41 44  HREADSAFE THREAD
31b0: 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64 65 66  SAFE.#else.# def
31c0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ine SQLITE_THREA
31d0: 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50 3a 20  DSAFE 1 /* IMP: 
31e0: 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20 2a 2f  R-07272-22309 */
31f0: 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a 0a  .#endif.#endif..
3200: 2f 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  /*.** The SQLITE
3210: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
3220: 55 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65  US macro must be
3230: 20 64 65 66 69 6e 65 64 20 61 73 20 65 69 74 68   defined as eith
3240: 65 72 20 30 20 6f 72 20 31 2e 0a 2a 2a 20 49 74  er 0 or 1..** It
3250: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 74   determines whet
3260: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
3270: 65 61 74 75 72 65 73 20 72 65 6c 61 74 65 64 20  eatures related 
3280: 74 6f 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  to .** SQLITE_CO
3290: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 61  NFIG_MEMSTATUS a
32a0: 72 65 20 61 76 61 69 6c 61 62 6c 65 20 62 79 20  re available by 
32b0: 64 65 66 61 75 6c 74 20 6f 72 20 6e 6f 74 2e 20  default or not. 
32c0: 54 68 69 73 20 76 61 6c 75 65 20 63 61 6e 0a 2a  This value can.*
32d0: 2a 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  * be overridden 
32e0: 61 74 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67  at runtime using
32f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
3300: 66 69 67 28 29 20 41 50 49 2e 0a 2a 2f 0a 23 69  fig() API..*/.#i
3310: 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54  f !defined(SQLIT
3320: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
3330: 54 55 53 29 0a 23 20 64 65 66 69 6e 65 20 53 51  TUS).# define SQ
3340: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
3350: 53 54 41 54 55 53 20 31 0a 23 65 6e 64 69 66 0a  STATUS 1.#endif.
3360: 0a 2f 2a 0a 2a 2a 20 45 78 61 63 74 6c 79 20 6f  ./*.** Exactly o
3370: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
3380: 69 6e 67 20 6d 61 63 72 6f 73 20 6d 75 73 74 20  ing macros must 
3390: 62 65 20 64 65 66 69 6e 65 64 20 69 6e 20 6f 72  be defined in or
33a0: 64 65 72 20 74 6f 0a 2a 2a 20 73 70 65 63 69 66  der to.** specif
33b0: 79 20 77 68 69 63 68 20 6d 65 6d 6f 72 79 20 61  y which memory a
33c0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
33d0: 74 65 6d 20 74 6f 20 75 73 65 2e 0a 2a 2a 0a 2a  tem to use..**.*
33e0: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 53 59 53  *     SQLITE_SYS
33f0: 54 45 4d 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  TEM_MALLOC      
3400: 20 20 20 20 2f 2f 20 55 73 65 20 6e 6f 72 6d 61      // Use norma
3410: 6c 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  l system malloc(
3420: 29 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  ).**     SQLITE_
3430: 4d 45 4d 44 45 42 55 47 20 20 20 20 20 20 20 20  MEMDEBUG        
3440: 20 20 20 20 20 20 20 2f 2f 20 44 65 62 75 67 67         // Debugg
3450: 69 6e 67 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  ing version of s
3460: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a  ystem malloc().*
3470: 2a 0a 2a 2a 20 28 48 69 73 74 6f 72 69 63 61 6c  *.** (Historical
3480: 20 6e 6f 74 65 3a 20 20 54 68 65 72 65 20 75 73   note:  There us
3490: 65 64 20 74 6f 20 62 65 20 73 65 76 65 72 61 6c  ed to be several
34a0: 20 6f 74 68 65 72 20 6f 70 74 69 6f 6e 73 2c 20   other options, 
34b0: 62 75 74 20 77 65 27 76 65 0a 2a 2a 20 70 61 72  but we've.** par
34c0: 65 64 20 69 74 20 64 6f 77 6e 20 74 6f 20 6a 75  ed it down to ju
34d0: 73 74 20 74 68 65 73 65 20 74 77 6f 2e 29 0a 2a  st these two.).*
34e0: 2a 0a 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20  *.** If none of 
34f0: 74 68 65 20 61 62 6f 76 65 20 61 72 65 20 64 65  the above are de
3500: 66 69 6e 65 64 2c 20 74 68 65 6e 20 73 65 74 20  fined, then set 
3510: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3520: 4c 4c 4f 43 20 61 73 0a 2a 2a 20 74 68 65 20 64  LLOC as.** the d
3530: 65 66 61 75 6c 74 2e 0a 2a 2f 0a 23 69 66 20 64  efault..*/.#if d
3540: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53 59  efined(SQLITE_SY
3550: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65 66  STEM_MALLOC)+def
3560: 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d 44  ined(SQLITE_MEMD
3570: 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f 72 20  EBUG)>1.# error 
3580: 22 41 74 20 6d 6f 73 74 20 6f 6e 65 20 6f 66 20  "At most one of 
3590: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
35a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 66 69  mpile-time confi
35b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
35c0: 5c 0a 20 69 73 20 61 6c 6c 6f 77 73 3a 20 53 51  \. is allows: SQ
35d0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
35e0: 4f 43 2c 20 53 51 4c 49 54 45 5f 4d 45 4d 44 45  OC, SQLITE_MEMDE
35f0: 42 55 47 22 0a 23 65 6e 64 69 66 0a 23 69 66 20  BUG".#endif.#if 
3600: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 53  defined(SQLITE_S
3610: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 29 2b 64 65  YSTEM_MALLOC)+de
3620: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d  fined(SQLITE_MEM
3630: 44 45 42 55 47 29 3d 3d 30 0a 23 20 64 65 66 69  DEBUG)==0.# defi
3640: 6e 65 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  ne SQLITE_SYSTEM
3650: 5f 4d 41 4c 4c 4f 43 20 31 0a 23 65 6e 64 69 66  _MALLOC 1.#endif
3660: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 53 51 4c 49 54  ../*.** If SQLIT
3670: 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49  E_MALLOC_SOFT_LI
3680: 4d 49 54 20 69 73 20 6e 6f 74 20 7a 65 72 6f 2c  MIT is not zero,
3690: 20 74 68 65 6e 20 74 72 79 20 74 6f 20 6b 65 65   then try to kee
36a0: 70 20 74 68 65 0a 2a 2a 20 73 69 7a 65 73 20 6f  p the.** sizes o
36b0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
36c0: 69 6f 6e 73 20 62 65 6c 6f 77 20 74 68 69 73 20  ions below this 
36d0: 76 61 6c 75 65 20 77 68 65 72 65 20 70 6f 73 73  value where poss
36e0: 69 62 6c 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  ible..*/.#if !de
36f0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 41 4c  fined(SQLITE_MAL
3700: 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 29 0a  LOC_SOFT_LIMIT).
3710: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3720: 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49  MALLOC_SOFT_LIMI
3730: 54 20 31 30 32 34 0a 23 65 6e 64 69 66 0a 0a 2f  T 1024.#endif../
3740: 2a 0a 2a 2a 20 57 65 20 6e 65 65 64 20 74 6f 20  *.** We need to 
3750: 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f 53 4f  define _XOPEN_SO
3760: 55 52 43 45 20 61 73 20 66 6f 6c 6c 6f 77 73 20  URCE as follows 
3770: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
3780: 6c 65 0a 2a 2a 20 72 65 63 75 72 73 69 76 65 20  le.** recursive 
3790: 6d 75 74 65 78 65 73 20 6f 6e 20 6d 6f 73 74 20  mutexes on most 
37a0: 55 6e 69 78 20 73 79 73 74 65 6d 73 2e 20 20 42  Unix systems.  B
37b0: 75 74 20 4d 61 63 20 4f 53 20 58 20 69 73 20 64  ut Mac OS X is d
37c0: 69 66 66 65 72 65 6e 74 2e 0a 2a 2a 20 54 68 65  ifferent..** The
37d0: 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 64   _XOPEN_SOURCE d
37e0: 65 66 69 6e 65 20 63 61 75 73 65 73 20 70 72 6f  efine causes pro
37f0: 62 6c 65 6d 73 20 66 6f 72 20 4d 61 63 20 4f 53  blems for Mac OS
3800: 20 58 20 77 65 20 61 72 65 20 74 6f 6c 64 2c 0a   X we are told,.
3810: 2a 2a 20 73 6f 20 69 74 20 69 73 20 6f 6d 69 74  ** so it is omit
3820: 74 65 64 20 74 68 65 72 65 2e 20 20 53 65 65 20  ted there.  See 
3830: 74 69 63 6b 65 74 20 23 32 36 37 33 2e 0a 2a 2a  ticket #2673..**
3840: 0a 2a 2a 20 4c 61 74 65 72 20 77 65 20 6c 65 61  .** Later we lea
3850: 72 6e 20 74 68 61 74 20 5f 58 4f 50 45 4e 5f 53  rn that _XOPEN_S
3860: 4f 55 52 43 45 20 69 73 20 70 6f 6f 72 6c 79 20  OURCE is poorly 
3870: 6f 72 20 69 6e 63 6f 72 72 65 63 74 6c 79 0a 2a  or incorrectly.*
3880: 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 6f 6e  * implemented on
3890: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 20 20   some systems.  
38a0: 53 6f 20 77 65 20 61 76 6f 69 64 20 64 65 66 69  So we avoid defi
38b0: 6e 69 6e 67 20 69 74 20 61 74 20 61 6c 6c 0a 2a  ning it at all.*
38c0: 2a 20 69 66 20 69 74 20 69 73 20 61 6c 72 65 61  * if it is alrea
38d0: 64 79 20 64 65 66 69 6e 65 64 20 6f 72 20 69 66  dy defined or if
38e0: 20 69 74 20 69 73 20 75 6e 6e 65 65 64 65 64 20   it is unneeded 
38f0: 62 65 63 61 75 73 65 20 77 65 20 61 72 65 0a 2a  because we are.*
3900: 2a 20 6e 6f 74 20 64 6f 69 6e 67 20 61 20 74 68  * not doing a th
3910: 72 65 61 64 73 61 66 65 20 62 75 69 6c 64 2e 20  readsafe build. 
3920: 20 54 69 63 6b 65 74 20 23 32 36 38 31 2e 0a 2a   Ticket #2681..*
3930: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 69  *.** See also ti
3940: 63 6b 65 74 20 23 32 37 34 31 2e 0a 2a 2f 0a 23  cket #2741..*/.#
3950: 69 66 20 21 64 65 66 69 6e 65 64 28 5f 58 4f 50  if !defined(_XOP
3960: 45 4e 5f 53 4f 55 52 43 45 29 20 26 26 20 21 64  EN_SOURCE) && !d
3970: 65 66 69 6e 65 64 28 5f 5f 44 41 52 57 49 4e 5f  efined(__DARWIN_
3980: 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  _) && !defined(_
3990: 5f 41 50 50 4c 45 5f 5f 29 20 26 26 20 53 51 4c  _APPLE__) && SQL
39a0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 0a 23  ITE_THREADSAFE.#
39b0: 20 20 64 65 66 69 6e 65 20 5f 58 4f 50 45 4e 5f    define _XOPEN_
39c0: 53 4f 55 52 43 45 20 35 30 30 20 20 2f 2a 20 4e  SOURCE 500  /* N
39d0: 65 65 64 65 64 20 74 6f 20 65 6e 61 62 6c 65 20  eeded to enable 
39e0: 70 74 68 72 65 61 64 20 72 65 63 75 72 73 69 76  pthread recursiv
39f0: 65 20 6d 75 74 65 78 65 73 20 2a 2f 0a 23 65 6e  e mutexes */.#en
3a00: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54  dif../*.** The T
3a10: 43 4c 20 68 65 61 64 65 72 73 20 61 72 65 20 6f  CL headers are o
3a20: 6e 6c 79 20 6e 65 65 64 65 64 20 77 68 65 6e 20  nly needed when 
3a30: 63 6f 6d 70 69 6c 69 6e 67 20 74 68 65 20 54 43  compiling the TC
3a40: 4c 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 23  L bindings..*/.#
3a50: 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  if defined(SQLIT
3a60: 45 5f 54 43 4c 29 20 7c 7c 20 64 65 66 69 6e 65  E_TCL) || define
3a70: 64 28 54 43 4c 53 48 29 0a 23 20 69 6e 63 6c 75  d(TCLSH).# inclu
3a80: 64 65 20 3c 74 63 6c 2e 68 3e 0a 23 65 6e 64 69  de <tcl.h>.#endi
3a90: 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6e 79 20 70 65  f../*.** Many pe
3aa0: 6f 70 6c 65 20 61 72 65 20 66 61 69 6c 69 6e 67  ople are failing
3ab0: 20 74 6f 20 73 65 74 20 2d 44 4e 44 45 42 55 47   to set -DNDEBUG
3ac0: 3d 31 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e  =1 when compilin
3ad0: 67 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 53 65 74  g SQLite..** Set
3ae0: 74 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65  ting NDEBUG make
3af0: 73 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c  s the code small
3b00: 65 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65  er and run faste
3b10: 72 2e 20 20 53 6f 20 74 68 65 20 66 6f 6c 6c 6f  r.  So the follo
3b20: 77 69 6e 67 0a 2a 2a 20 6c 69 6e 65 73 20 61 72  wing.** lines ar
3b30: 65 20 61 64 64 65 64 20 74 6f 20 61 75 74 6f 6d  e added to autom
3b40: 61 74 69 63 61 6c 6c 79 20 73 65 74 20 4e 44 45  atically set NDE
3b50: 42 55 47 20 75 6e 6c 65 73 73 20 74 68 65 20 2d  BUG unless the -
3b60: 44 53 51 4c 49 54 45 5f 44 45 42 55 47 3d 31 0a  DSQLITE_DEBUG=1.
3b70: 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  ** option is set
3b80: 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20 62  .  Thus NDEBUG b
3b90: 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69 6e  ecomes an opt-in
3ba0: 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e 20   rather than an 
3bb0: 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74 75  opt-out.** featu
3bc0: 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69  re..*/.#if !defi
3bd0: 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20 21  ned(NDEBUG) && !
3be0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
3bf0: 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65 20  EBUG) .# define 
3c00: 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66 0a  NDEBUG 1.#endif.
3c10: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 65 73 74 63  ./*.** The testc
3c20: 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73 20 75  ase() macro is u
3c30: 73 65 64 20 74 6f 20 61 69 64 20 69 6e 20 63 6f  sed to aid in co
3c40: 76 65 72 61 67 65 20 74 65 73 74 69 6e 67 2e 20  verage testing. 
3c50: 20 57 68 65 6e 20 0a 2a 2a 20 64 6f 69 6e 67 20   When .** doing 
3c60: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67  coverage testing
3c70: 2c 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 20  , the condition 
3c80: 69 6e 73 69 64 65 20 74 68 65 20 61 72 67 75 6d  inside the argum
3c90: 65 6e 74 20 74 6f 0a 2a 2a 20 74 65 73 74 63 61  ent to.** testca
3ca0: 73 65 28 29 20 6d 75 73 74 20 62 65 20 65 76 61  se() must be eva
3cb0: 6c 75 61 74 65 64 20 62 6f 74 68 20 74 72 75 65  luated both true
3cc0: 20 61 6e 64 20 66 61 6c 73 65 20 69 6e 20 6f 72   and false in or
3cd0: 64 65 72 20 74 6f 0a 2a 2a 20 67 65 74 20 66 75  der to.** get fu
3ce0: 6c 6c 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61  ll branch covera
3cf0: 67 65 2e 20 20 54 68 65 20 74 65 73 74 63 61 73  ge.  The testcas
3d00: 65 28 29 20 6d 61 63 72 6f 20 69 73 20 69 6e 73  e() macro is ins
3d10: 65 72 74 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70  erted.** to help
3d20: 20 65 6e 73 75 72 65 20 61 64 65 71 75 61 74 65   ensure adequate
3d30: 20 74 65 73 74 20 63 6f 76 65 72 61 67 65 20 69   test coverage i
3d40: 6e 20 70 6c 61 63 65 73 20 77 68 65 72 65 20 73  n places where s
3d50: 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e 64 69 74 69  imple.** conditi
3d60: 6f 6e 2f 64 65 63 69 73 69 6f 6e 20 63 6f 76 65  on/decision cove
3d70: 72 61 67 65 20 69 73 20 69 6e 61 64 65 71 75 61  rage is inadequa
3d80: 74 65 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  te.  For example
3d90: 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a 20  , testcase().** 
3da0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d  can be used to m
3db0: 61 6b 65 20 73 75 72 65 20 62 6f 75 6e 64 61 72  ake sure boundar
3dc0: 79 20 76 61 6c 75 65 73 20 61 72 65 20 74 65 73  y values are tes
3dd0: 74 65 64 2e 20 20 46 6f 72 0a 2a 2a 20 62 69 74  ted.  For.** bit
3de0: 6d 61 73 6b 20 74 65 73 74 73 2c 20 74 65 73 74  mask tests, test
3df0: 63 61 73 65 28 29 20 63 61 6e 20 62 65 20 75 73  case() can be us
3e00: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  ed to make sure 
3e10: 65 61 63 68 20 62 69 74 0a 2a 2a 20 69 73 20 73  each bit.** is s
3e20: 69 67 6e 69 66 69 63 61 6e 74 20 61 6e 64 20 75  ignificant and u
3e30: 73 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  sed at least onc
3e40: 65 2e 20 20 4f 6e 20 73 77 69 74 63 68 20 73 74  e.  On switch st
3e50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 77 68 65 72  atements.** wher
3e60: 65 20 6d 75 6c 74 69 70 6c 65 20 63 61 73 65 73  e multiple cases
3e70: 20 67 6f 20 74 6f 20 74 68 65 20 73 61 6d 65 20   go to the same 
3e80: 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 2c 20 74  block of code, t
3e90: 65 73 74 63 61 73 65 28 29 0a 2a 2a 20 63 61 6e  estcase().** can
3ea0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 61 6c 6c   insure that all
3eb0: 20 63 61 73 65 73 20 61 72 65 20 65 76 61 6c 75   cases are evalu
3ec0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 64  ated..**.*/.#ifd
3ed0: 65 66 20 53 51 4c 49 54 45 5f 43 4f 56 45 52 41  ef SQLITE_COVERA
3ee0: 47 45 5f 54 45 53 54 0a 53 51 4c 49 54 45 5f 50  GE_TEST.SQLITE_P
3ef0: 52 49 56 41 54 45 20 20 20 76 6f 69 64 20 73 71  RIVATE   void sq
3f00: 6c 69 74 65 33 43 6f 76 65 72 61 67 65 28 69 6e  lite3Coverage(in
3f10: 74 29 3b 0a 23 20 64 65 66 69 6e 65 20 74 65 73  t);.# define tes
3f20: 74 63 61 73 65 28 58 29 20 20 69 66 28 20 58 20  tcase(X)  if( X 
3f30: 29 7b 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61  ){ sqlite3Covera
3f40: 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29 3b 20 7d 0a  ge(__LINE__); }.
3f50: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 74  #else.# define t
3f60: 65 73 74 63 61 73 65 28 58 29 0a 23 65 6e 64 69  estcase(X).#endi
3f70: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 54 45 53  f../*.** The TES
3f80: 54 4f 4e 4c 59 20 6d 61 63 72 6f 20 69 73 20 75  TONLY macro is u
3f90: 73 65 64 20 74 6f 20 65 6e 63 6c 6f 73 65 20 76  sed to enclose v
3fa0: 61 72 69 61 62 6c 65 20 64 65 63 6c 61 72 61 74  ariable declarat
3fb0: 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f 74 68 65 72  ions or.** other
3fc0: 20 62 69 74 73 20 6f 66 20 63 6f 64 65 20 74 68   bits of code th
3fd0: 61 74 20 61 72 65 20 6e 65 65 64 65 64 20 74 6f  at are needed to
3fe0: 20 73 75 70 70 6f 72 74 20 74 68 65 20 61 72 67   support the arg
3ff0: 75 6d 65 6e 74 73 0a 2a 2a 20 77 69 74 68 69 6e  uments.** within
4000: 20 74 65 73 74 63 61 73 65 28 29 20 61 6e 64 20   testcase() and 
4010: 61 73 73 65 72 74 28 29 20 6d 61 63 72 6f 73 2e  assert() macros.
4020: 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64  .*/.#if !defined
4030: 28 4e 44 45 42 55 47 29 20 7c 7c 20 64 65 66 69  (NDEBUG) || defi
4040: 6e 65 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52  ned(SQLITE_COVER
4050: 41 47 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69  AGE_TEST).# defi
4060: 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29 20 20  ne TESTONLY(X)  
4070: 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  X.#else.# define
4080: 20 54 45 53 54 4f 4e 4c 59 28 58 29 0a 23 65 6e   TESTONLY(X).#en
4090: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53 6f 6d 65 74  dif../*.** Somet
40a0: 69 6d 65 73 20 77 65 20 6e 65 65 64 20 61 20 73  imes we need a s
40b0: 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 63  mall amount of c
40c0: 6f 64 65 20 73 75 63 68 20 61 73 20 61 20 76 61  ode such as a va
40d0: 72 69 61 62 6c 65 20 69 6e 69 74 69 61 6c 69 7a  riable initializ
40e0: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 73 65 74 75  ation.** to setu
40f0: 70 20 66 6f 72 20 61 20 6c 61 74 65 72 20 61 73  p for a later as
4100: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
4110: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 77 61 6e  .  We do not wan
4120: 74 20 74 68 69 73 20 63 6f 64 65 20 74 6f 0a 2a  t this code to.*
4130: 2a 20 61 70 70 65 61 72 20 77 68 65 6e 20 61 73  * appear when as
4140: 73 65 72 74 28 29 20 69 73 20 64 69 73 61 62 6c  sert() is disabl
4150: 65 64 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ed.  The followi
4160: 6e 67 20 6d 61 63 72 6f 20 69 73 20 74 68 65 72  ng macro is ther
4170: 65 66 6f 72 65 0a 2a 2a 20 75 73 65 64 20 74 6f  efore.** used to
4180: 20 63 6f 6e 74 61 69 6e 20 74 68 61 74 20 73 65   contain that se
4190: 74 75 70 20 63 6f 64 65 2e 20 20 54 68 65 20 22  tup code.  The "
41a0: 56 56 41 22 20 61 63 72 6f 6e 79 6d 20 73 74 61  VVA" acronym sta
41b0: 6e 64 73 20 66 6f 72 0a 2a 2a 20 22 56 65 72 69  nds for.** "Veri
41c0: 66 69 63 61 74 69 6f 6e 2c 20 56 61 6c 69 64 61  fication, Valida
41d0: 74 69 6f 6e 2c 20 61 6e 64 20 41 63 63 72 65 64  tion, and Accred
41e0: 69 74 61 74 69 6f 6e 22 2e 20 20 49 6e 20 6f 74  itation".  In ot
41f0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 0a 2a  her words, the.*
4200: 2a 20 63 6f 64 65 20 77 69 74 68 69 6e 20 56 56  * code within VV
4210: 41 5f 4f 4e 4c 59 28 29 20 77 69 6c 6c 20 6f 6e  A_ONLY() will on
4220: 6c 79 20 72 75 6e 20 64 75 72 69 6e 67 20 76 65  ly run during ve
4230: 72 69 66 69 63 61 74 69 6f 6e 20 70 72 6f 63 65  rification proce
4240: 73 73 65 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  sses..*/.#ifndef
4250: 20 4e 44 45 42 55 47 0a 23 20 64 65 66 69 6e 65   NDEBUG.# define
4260: 20 56 56 41 5f 4f 4e 4c 59 28 58 29 20 20 58 0a   VVA_ONLY(X)  X.
4270: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 56  #else.# define V
4280: 56 41 5f 4f 4e 4c 59 28 58 29 0a 23 65 6e 64 69  VA_ONLY(X).#endi
4290: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 41 4c 57  f../*.** The ALW
42a0: 41 59 53 20 61 6e 64 20 4e 45 56 45 52 20 6d 61  AYS and NEVER ma
42b0: 63 72 6f 73 20 73 75 72 72 6f 75 6e 64 20 62 6f  cros surround bo
42c0: 6f 6c 65 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  olean expression
42d0: 73 20 77 68 69 63 68 20 0a 2a 2a 20 61 72 65 20  s which .** are 
42e0: 69 6e 74 65 6e 64 65 64 20 74 6f 20 61 6c 77 61  intended to alwa
42f0: 79 73 20 62 65 20 74 72 75 65 20 6f 72 20 66 61  ys be true or fa
4300: 6c 73 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  lse, respectivel
4310: 79 2e 20 20 53 75 63 68 0a 2a 2a 20 65 78 70 72  y.  Such.** expr
4320: 65 73 73 69 6f 6e 73 20 63 6f 75 6c 64 20 62 65  essions could be
4330: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
4340: 65 20 63 6f 64 65 20 63 6f 6d 70 6c 65 74 65 6c  e code completel
4350: 79 2e 20 20 42 75 74 20 74 68 65 79 0a 2a 2a 20  y.  But they.** 
4360: 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
4370: 61 20 66 65 77 20 63 61 73 65 73 20 69 6e 20 6f  a few cases in o
4380: 72 64 65 72 20 74 6f 20 65 6e 68 61 6e 63 65 20  rder to enhance 
4390: 74 68 65 20 72 65 73 69 6c 69 65 6e 63 65 0a 2a  the resilience.*
43a0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 75  * of SQLite to u
43b0: 6e 65 78 70 65 63 74 65 64 20 62 65 68 61 76 69  nexpected behavi
43c0: 6f 72 20 2d 20 74 6f 20 6d 61 6b 65 20 74 68 65  or - to make the
43d0: 20 63 6f 64 65 20 22 73 65 6c 66 2d 68 65 61 6c   code "self-heal
43e0: 69 6e 67 22 0a 2a 2a 20 6f 72 20 22 64 75 63 74  ing".** or "duct
43f0: 69 6c 65 22 20 72 61 74 68 65 72 20 74 68 61 6e  ile" rather than
4400: 20 62 65 69 6e 67 20 22 62 72 69 74 74 6c 65 22   being "brittle"
4410: 20 61 6e 64 20 63 72 61 73 68 69 6e 67 20 61 74   and crashing at
4420: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 68 69   the first.** hi
4430: 6e 74 20 6f 66 20 75 6e 70 6c 61 6e 6e 65 64 20  nt of unplanned 
4440: 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
4450: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
4460: 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45 52  ALWAYS and NEVER
4470: 20 61 72 65 20 61 64 64 65 64 20 66 6f 72 20 64   are added for d
4480: 65 66 65 6e 73 69 76 65 20 63 6f 64 65 2e 0a 2a  efensive code..*
4490: 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f 69 6e 67 20  *.** When doing 
44a0: 63 6f 76 65 72 61 67 65 20 74 65 73 74 69 6e 67  coverage testing
44b0: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
44c0: 52 20 61 72 65 20 68 61 72 64 2d 63 6f 64 65 64  R are hard-coded
44d0: 20 74 6f 0a 2a 2a 20 62 65 20 74 72 75 65 20 61   to.** be true a
44e0: 6e 64 20 66 61 6c 73 65 20 73 6f 20 74 68 61 74  nd false so that
44f0: 20 74 68 65 20 75 6e 72 65 61 63 68 61 62 6c 65   the unreachable
4500: 20 63 6f 64 65 20 74 68 65 6e 20 73 70 65 63 69   code then speci
4510: 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e 6f 74 20 62  fy will.** not b
4520: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 75 6e 74  e counted as unt
4530: 65 73 74 65 64 20 63 6f 64 65 2e 0a 2a 2f 0a 23  ested code..*/.#
4540: 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  if defined(SQLIT
4550: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29  E_COVERAGE_TEST)
4560: 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53  .# define ALWAYS
4570: 28 58 29 20 20 20 20 20 20 28 31 29 0a 23 20 64  (X)      (1).# d
4580: 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20 20  efine NEVER(X)  
4590: 20 20 20 20 20 28 30 29 0a 23 65 6c 69 66 20 21       (0).#elif !
45a0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 0a  defined(NDEBUG).
45b0: 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59 53 28  # define ALWAYS(
45c0: 58 29 20 20 20 20 20 20 28 28 58 29 3f 31 3a 28  X)      ((X)?1:(
45d0: 61 73 73 65 72 74 28 30 29 2c 30 29 29 0a 23 20  assert(0),0)).# 
45e0: 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20  define NEVER(X) 
45f0: 20 20 20 20 20 20 28 28 58 29 3f 28 61 73 73 65        ((X)?(asse
4600: 72 74 28 30 29 2c 31 29 3a 30 29 0a 23 65 6c 73  rt(0),1):0).#els
4610: 65 0a 23 20 64 65 66 69 6e 65 20 41 4c 57 41 59  e.# define ALWAY
4620: 53 28 58 29 20 20 20 20 20 20 28 58 29 0a 23 20  S(X)      (X).# 
4630: 64 65 66 69 6e 65 20 4e 45 56 45 52 28 58 29 20  define NEVER(X) 
4640: 20 20 20 20 20 20 28 58 29 0a 23 65 6e 64 69 66        (X).#endif
4650: 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  ../*.** Return t
4660: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
4670: 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
4680: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
4690: 20 74 6f 6f 20 6c 61 72 67 65 0a 2a 2a 20 74 6f   too large.** to
46a0: 20 66 69 74 20 69 6e 20 33 32 2d 62 69 74 73 2e   fit in 32-bits.
46b0: 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 20    This macro is 
46c0: 75 73 65 64 20 69 6e 73 69 64 65 20 6f 66 20 76  used inside of v
46d0: 61 72 69 6f 75 73 20 74 65 73 74 63 61 73 65 28  arious testcase(
46e0: 29 0a 2a 2a 20 6d 61 63 72 6f 73 20 74 6f 20 76  ).** macros to v
46f0: 65 72 69 66 79 20 74 68 61 74 20 77 65 20 68 61  erify that we ha
4700: 76 65 20 74 65 73 74 65 64 20 53 51 4c 69 74 65  ve tested SQLite
4710: 20 66 6f 72 20 6c 61 72 67 65 2d 66 69 6c 65 20   for large-file 
4720: 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 64 65 66  support..*/.#def
4730: 69 6e 65 20 49 53 5f 42 49 47 5f 49 4e 54 28 58  ine IS_BIG_INT(X
4740: 29 20 20 28 28 28 58 29 26 7e 28 69 36 34 29 30  )  (((X)&~(i64)0
4750: 78 66 66 66 66 66 66 66 66 29 21 3d 30 29 0a 0a  xffffffff)!=0)..
4760: 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 63 72 6f 20  /*.** The macro 
4770: 75 6e 6c 69 6b 65 6c 79 28 29 20 69 73 20 61 20  unlikely() is a 
4780: 68 69 6e 74 20 74 68 61 74 20 73 75 72 72 6f 75  hint that surrou
4790: 6e 64 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a  nds a boolean.**
47a0: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
47b0: 20 69 73 20 75 73 75 61 6c 6c 79 20 66 61 6c 73   is usually fals
47c0: 65 2e 20 20 4d 61 63 72 6f 20 6c 69 6b 65 6c 79  e.  Macro likely
47d0: 28 29 20 73 75 72 72 6f 75 6e 64 73 0a 2a 2a 20  () surrounds.** 
47e0: 61 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  a boolean expres
47f0: 73 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75  sion that is usu
4800: 61 6c 6c 79 20 74 72 75 65 2e 20 20 47 43 43 20  ally true.  GCC 
4810: 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 75 73  is able to.** us
4820: 65 20 74 68 65 73 65 20 68 69 6e 74 73 20 74 6f  e these hints to
4830: 20 67 65 6e 65 72 61 74 65 20 62 65 74 74 65 72   generate better
4840: 20 63 6f 64 65 2c 20 73 6f 6d 65 74 69 6d 65 73   code, sometimes
4850: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
4860: 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 30 0a  (__GNUC__) && 0.
4870: 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c 79 28  # define likely(
4880: 58 29 20 20 20 20 5f 5f 62 75 69 6c 74 69 6e 5f  X)    __builtin_
4890: 65 78 70 65 63 74 28 28 58 29 2c 31 29 0a 23 20  expect((X),1).# 
48a0: 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28  define unlikely(
48b0: 58 29 20 20 5f 5f 62 75 69 6c 74 69 6e 5f 65 78  X)  __builtin_ex
48c0: 70 65 63 74 28 28 58 29 2c 30 29 0a 23 65 6c 73  pect((X),0).#els
48d0: 65 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b 65 6c  e.# define likel
48e0: 79 28 58 29 20 20 20 20 21 21 28 58 29 0a 23 20  y(X)    !!(X).# 
48f0: 64 65 66 69 6e 65 20 75 6e 6c 69 6b 65 6c 79 28  define unlikely(
4900: 58 29 20 20 21 21 28 58 29 0a 23 65 6e 64 69 66  X)  !!(X).#endif
4910: 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ../*************
4920: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
4930: 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c  3.h in the middl
4940: 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68  e of sqliteInt.h
4950: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
4960: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
4970: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
4980: 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ite3.h *********
4990: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
49b0: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70  /./*.** 2001 Sep
49c0: 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20  tember 15.**.** 
49d0: 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c  The author discl
49e0: 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74  aims copyright t
49f0: 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f  o this source co
4a00: 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66  de.  In place of
4a10: 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69  .** a legal noti
4a20: 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c  ce, here is a bl
4a30: 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20  essing:.**.**   
4a40: 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64   May you do good
4a50: 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a   and not evil..*
4a60: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e  *    May you fin
4a70: 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f  d forgiveness fo
4a80: 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66  r yourself and f
4a90: 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a  orgive others..*
4aa0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61  *    May you sha
4ab0: 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72  re freely, never
4ac0: 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61   taking more tha
4ad0: 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a  n you give..**.*
4ae0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b20: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  ********.** This
4b30: 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 65 66   header file def
4b40: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
4b50: 63 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  ce that the SQLi
4b60: 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72  te library.** pr
4b70: 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74  esents to client
4b80: 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61   programs.  If a
4b90: 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72   C-function, str
4ba0: 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 70 65  ucture, datatype
4bb0: 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74  ,.** or constant
4bc0: 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73   definition does
4bd0: 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74   not appear in t
4be0: 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69  his file, then i
4bf0: 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75  t is.** not a pu
4c00: 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 20 53  blished API of S
4c10: 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63  QLite, is subjec
4c20: 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
4c30: 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61  out.** notice, a
4c40: 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
4c50: 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 70   referenced by p
4c60: 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 73 65  rograms that use
4c70: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4c80: 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e  ome of the defin
4c90: 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  itions that are 
4ca0: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 72 65  in this file are
4cb0: 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65   marked as.** "e
4cc0: 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45  xperimental".  E
4cd0: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
4ce0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61  rfaces are norma
4cf0: 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75  lly new.** featu
4d00: 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64  res recently add
4d10: 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57  ed to SQLite.  W
4d20: 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70  e do not anticip
4d30: 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74  ate changes.** t
4d40: 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  o experimental i
4d50: 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65  nterfaces but re
4d60: 73 65 72 76 65 20 74 68 65 20 72 69 67 68 74 20  serve the right 
4d70: 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68  to make minor ch
4d80: 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65  anges.** if expe
4d90: 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20  rience from use 
4da0: 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75  "in the wild" su
4db0: 67 67 65 73 74 20 73 75 63 68 20 63 68 61 6e 67  ggest such chang
4dc0: 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a  es are prudent..
4dd0: 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69  **.** The offici
4de0: 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50  al C-language AP
4df0: 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  I documentation 
4e00: 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 64 65  for SQLite is de
4e10: 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f  rived.** from co
4e20: 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66  mments in this f
4e30: 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20  ile.  This file 
4e40: 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 74 61  is the authorita
4e50: 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f  tive source.** o
4e60: 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74  n how SQLite int
4e70: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 70 70  erfaces are supp
4e80: 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a  ose to operate..
4e90: 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
4ea0: 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65  f this file unde
4eb0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
4ec0: 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73  management is "s
4ed0: 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20  qlite.h.in"..** 
4ee0: 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b  The makefile mak
4ef0: 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68  es some minor ch
4f00: 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69  anges to this fi
4f10: 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65  le (such as inse
4f20: 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72  rting.** the ver
4f30: 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64  sion number) and
4f40: 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d   changes its nam
4f50: 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22  e to "sqlite3.h"
4f60: 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
4f70: 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73  he build process
4f80: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  ..*/.#ifndef _SQ
4f90: 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65  LITE3_H_.#define
4fa0: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e   _SQLITE3_H_.#in
4fb0: 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e  clude <stdarg.h>
4fc0: 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66       /* Needed f
4fd0: 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f  or the definitio
4fe0: 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a  n of va_list */.
4ff0: 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65  ./*.** Make sure
5000: 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69   we can call thi
5010: 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b  s stuff from C++
5020: 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72  ..*/.#if 0.exter
5030: 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a  n "C" {.#endif..
5040: 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68 65 20 61  ./*.** Add the a
5050: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
5060: 64 65 20 27 65 78 74 65 72 6e 27 0a 2a 2f 0a 23  de 'extern'.*/.#
5070: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58  ifndef SQLITE_EX
5080: 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51  TERN.# define SQ
5090: 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65  LITE_EXTERN exte
50a0: 72 6e 0a 23 65 6e 64 69 66 0a 0a 23 69 66 6e 64  rn.#endif..#ifnd
50b0: 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20  ef SQLITE_API.# 
50c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50  define SQLITE_AP
50d0: 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a  I.#endif.../*.**
50e0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
50f0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
5100: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
5110: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
5120: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
5130: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
5140: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
5150: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
5160: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
5170: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
5180: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
5190: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
51a0: 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  rt for backwards
51b0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
51c0: 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  y only.  Applica
51d0: 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f  tion writers sho
51e0: 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61  uld be aware tha
51f0: 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  t.** experimenta
5200: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
5210: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
5220: 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65  ge in point rele
5230: 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ases..**.** Thes
5240: 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f  e macros used to
5250: 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69   resolve to vari
5260: 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d  ous kinds of com
5270: 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74  piler magic that
5280: 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61  .** would genera
5290: 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61  te warning messa
52a0: 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65  ges when they we
52b0: 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68  re used.  But th
52c0: 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d  at.** compiler m
52d0: 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65  agic ended up ge
52e0: 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20  nerating such a 
52f0: 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65  flurry of bug re
5300: 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65  ports.** that we
5310: 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61   have taken it a
5320: 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20  ll out and gone 
5330: 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69  back to using si
5340: 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63  mple.** noop mac
5350: 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ros..*/.#define 
5360: 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
5370: 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  D.#define SQLITE
5380: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f  _EXPERIMENTAL../
5390: 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73  *.** Ensure thes
53a0: 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e  e symbols were n
53b0: 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f  ot defined by so
53c0: 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64  me previous head
53d0: 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64  er file..*/.#ifd
53e0: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
53f0: 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  N.# undef SQLITE
5400: 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a  _VERSION.#endif.
5410: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
5420: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75  RSION_NUMBER.# u
5430: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
5440: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69  ION_NUMBER.#endi
5450: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
5460: 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
5470: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5480: 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28  Numbers.**.** ^(
5490: 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  The [SQLITE_VERS
54a0: 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73  ION] C preproces
54b0: 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65  sor macro in the
54c0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
54d0: 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74  r.** evaluates t
54e0: 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
54f0: 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53  al that is the S
5500: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e  QLite version in
5510: 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22   the.** format "
5520: 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69  X.Y.Z" where X i
5530: 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  s the major vers
5540: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61  ion number (alwa
5550: 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69  ys 3 for.** SQLi
5560: 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68  te3) and Y is th
5570: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
5580: 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20  number and Z is 
5590: 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  the release numb
55a0: 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b  er.)^.** ^(The [
55b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
55c0: 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63  UMBER] C preproc
55d0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f  essor macro reso
55e0: 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67  lves to an integ
55f0: 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  er.** with the v
5600: 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20  alue (X*1000000 
5610: 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68  + Y*1000 + Z) wh
5620: 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20  ere X, Y, and Z 
5630: 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  are the same.** 
5640: 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20  numbers used in 
5650: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
5660: 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .)^.** The SQLIT
5670: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5680: 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72   for any given r
5690: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
56a0: 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
56b0: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
56c0: 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68   release from wh
56d0: 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65  ich it is derive
56e0: 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c  d.  Either Y wil
56f0: 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e  l.** be held con
5700: 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c  stant and Z will
5710: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   be incremented 
5720: 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62  or else Y will b
5730: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a  e incremented.**
5740: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72   and Z will be r
5750: 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a  eset to zero..**
5760: 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 6f  .** Since versio
5770: 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65  n 3.6.18, SQLite
5780: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
5790: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
57a0: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
57b0: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
57c0: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
57d0: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
57e0: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
57f0: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
5800: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5810: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
5820: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
5830: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
5840: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
5850: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
5860: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
5870: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
5880: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
5890: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
58a0: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
58b0: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
58c0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
58d0: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
58e0: 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a  C) and an SHA1.*
58f0: 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e  * hash of the en
5900: 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 65  tire source tree
5910: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
5920: 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  : [sqlite3_libve
5930: 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rsion()],.** [sq
5940: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5950: 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c  _number()], [sql
5960: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 5d  ite3_sourceid()]
5970: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72  ,.** [sqlite_ver
5980: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
5990: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
59a0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
59b0: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
59c0: 20 20 20 22 33 2e 37 2e 37 22 0a 23 64 65 66 69     "3.7.7".#defi
59d0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
59e0: 4e 5f 4e 55 4d 42 45 52 20 33 30 30 37 30 30 37  N_NUMBER 3007007
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
5a10: 32 30 31 31 2d 30 37 2d 31 33 20 31 36 3a 30 33  2011-07-13 16:03
5a20: 3a 34 36 20 37 61 61 66 30 61 36 61 65 31 32 33  :46 7aaf0a6ae123
5a30: 38 31 32 39 65 30 37 65 62 31 39 31 63 61 33 66  8129e07eb191ca3f
5a40: 30 34 33 64 66 34 34 35 65 32 37 61 22 0a 0a 2f  043df445e27a"../
5a50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
5a60: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
5a70: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
5a80: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
5a90: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
5aa0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
5ab0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
5ac0: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
5ad0: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
5ae0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
5af0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
5b00: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
5b10: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
5b20: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
5b30: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
5b40: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
5b50: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
5b60: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
5b70: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
5b80: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
5b90: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
5ba0: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
5bb0: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
5bc0: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
5bd0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
5be0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
5bf0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
5c00: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
5c10: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
5c20: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
5c30: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
5c40: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
5c50: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
5c60: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
5c70: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
5c80: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
5c90: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
5ca0: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
5cb0: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
5cc0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
5cd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5ce0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
5cf0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
5d00: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
5d10: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
5d20: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
5d30: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
5d40: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
5d50: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
5d60: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
5d70: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
5d80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
5d90: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
5da0: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
5db0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
5dc0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
5dd0: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
5de0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
5df0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
5e00: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
5e10: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
5e20: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
5e30: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
5e40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
5e50: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
5e60: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
5e80: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
5e90: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
5ea0: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
5eb0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
5ec0: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
5ed0: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
5ee0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
5ef0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
5f00: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
5f10: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
5f20: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
5f30: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5f40: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
5f50: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
5f60: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
5f70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
5f80: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5f90: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
5fa0: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
5fb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
5fc0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
5fd0: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
5fe0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
5ff0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
6000: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
6010: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
6020: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6030: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
6040: 6e 5b 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52  n[] = SQLITE_VER
6050: 53 49 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49  SION;.SQLITE_API
6060: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
6070: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
6080: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
6090: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
60a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
60b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
60c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
60d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
60e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
60f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
6100: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
6110: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
6120: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
6130: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
6140: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
6150: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
6160: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
6170: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
6180: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
6190: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
61a0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
61b0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
61c0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
61d0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
61e0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
61f0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
6200: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6210: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
6220: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
6230: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6240: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
6250: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
6260: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
6270: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
6280: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
6290: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
62a0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
62b0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
62c0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
62d0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
62e0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
62f0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6300: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
6310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
6320: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
6330: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
6340: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
6350: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
6360: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
6370: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
6380: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
6390: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
63a0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
63b0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
63c0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
63d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
63e0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
63f0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
6400: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
6410: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
6420: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
6430: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
6440: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
6450: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
6460: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
6470: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
6480: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
6490: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
64a0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
64b0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
64c0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
64d0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
64e0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
64f0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
6500: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
6510: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6520: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
6530: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
6540: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
6550: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
6560: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
6570: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
6580: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
6590: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
65a0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
65b0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
65c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
65d0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
65e0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
65f0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
6600: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
6610: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
6620: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
6630: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
6640: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
6650: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
6660: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
6670: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
6680: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
6690: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
66a0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
66b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
66c0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
66d0: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
66e0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
66f0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
6700: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
6710: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
6720: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
6730: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
6740: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
6750: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
6760: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
6770: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
6780: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
6790: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
67a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
67b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
67c0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
67d0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
67e0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
67f0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
6800: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
6810: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
6820: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
6830: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
6840: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
6850: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
6860: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
6870: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
6880: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
6890: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
68a0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
68b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
68c0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
68d0: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
68e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
68f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
6900: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
6910: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
6920: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
6930: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
6940: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
6950: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
6960: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
6970: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
6980: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
6990: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
69a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
69b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
69c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
69d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
69e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
69f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
6a00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
6a10: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
6a20: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
6a30: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
6a40: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
6a50: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
6a60: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
6a70: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
6a80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
6a90: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
6aa0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
6ab0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
6ac0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ad0: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
6ae0: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
6af0: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
6b00: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
6b10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
6b20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6b30: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
6b40: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
6b50: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
6b60: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
6b70: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
6b80: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
6b90: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
6ba0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
6bb0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
6bc0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
6bd0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
6be0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
6bf0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
6c00: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
6c10: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
6c20: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
6c30: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
6c40: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
6c50: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
6c60: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
6c70: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6c80: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
6c90: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
6ca0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
6cb0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
6cc0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
6cd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6ce0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
6cf0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
6d00: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
6d10: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
6d20: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
6d30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
6d40: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
6d50: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
6d60: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
6d70: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
6d80: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
6d90: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
6da0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
6db0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
6dc0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
6dd0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
6df0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
6e00: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
6e10: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
6e20: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69  e3_close()].** i
6e30: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
6e40: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
6e50: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
6e60: 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b  es (such as.** [
6e70: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
6e80: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
6e90: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
6ea0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
6eb0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
6ec0: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
6ed0: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
6ee0: 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a  methods on an.**
6ef0: 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e   sqlite3 object.
6f00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
6f10: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
6f20: 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e3;../*.** CAPI3
6f30: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65  REF: 64-Bit Inte
6f40: 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59  ger Types.** KEY
6f50: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
6f60: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
6f70: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
6f80: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
6f90: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
6fa0: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
6fb0: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
6fc0: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
6fd0: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
6fe0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
6ff0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
7000: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
7010: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
7020: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7030: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
7040: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
7050: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
7060: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
7070: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
7080: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
7090: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
70a0: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
70b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
70c0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
70d0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65  qlite_int64 type
70e0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
70f0: 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  ger values.** be
7100: 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33  tween -922337203
7110: 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b  6854775808 and +
7120: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
7130: 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20  807 inclusive.  
7140: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
7150: 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  uint64 and sqlit
7160: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63  e_uint64 types c
7170: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
7180: 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77   values .** betw
7190: 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36  een 0 and +18446
71a0: 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20  744073709551615 
71b0: 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69  inclusive..*/.#i
71c0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
71d0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
71e0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
71f0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
7200: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
7210: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
7220: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
7230: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
7240: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
7250: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
7260: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
7270: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
7280: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
7290: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
72a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
72b0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
72c0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
72d0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
72e0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
72f0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
7300: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
7310: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
7320: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
7330: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
7340: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
7350: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
7360: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
7370: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
7380: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
7390: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
73a0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
73b0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
73c0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
73d0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
73e0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
73f0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
7400: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
7410: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
7420: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
7430: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
7440: 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
7450: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
7460: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  ) routine is the
7470: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
7480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
7490: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  ject..** ^Calls 
74a0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  to sqlite3_close
74b0: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
74c0: 5f 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69  _OK if the [sqli
74d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a  te3] object is.*
74e0: 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  * successfully d
74f0: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
7500: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
7510: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
7520: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
7530: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
7540: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
7550: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
7560: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
7570: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
7580: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
7590: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
75a0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
75b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
75c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
75d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
75e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
75f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
7600: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
7610: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
7620: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
7630: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
7640: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
7650: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
7660: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
7670: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
7680: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
7690: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
76a0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
76b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
76c0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
76d0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
76e0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
76f0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
7700: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
7710: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
7720: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
7730: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
7740: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
7750: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
7760: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
7770: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
7780: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
7790: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
77a0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
77b0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
77c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
77d0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
77e0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
77f0: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
7800: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
7810: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
7820: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
7830: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
7840: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
7850: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
7860: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
7870: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
7880: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
7890: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
78a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
78b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
78c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
78d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
78e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
78f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
7900: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
7910: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
7920: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
7930: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
7940: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7950: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
7960: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
7970: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ce.**.** The sql
7980: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
7990: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
79a0: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
79b0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
79c0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
79d0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
79e0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
79f0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
7a00: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
7a10: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
7a20: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
7a30: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
7a40: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
7a50: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
7a60: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
7a70: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
7a80: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
7a90: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
7aa0: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
7ab0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
7ac0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
7ad0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
7ae0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
7af0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
7b00: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
7b10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
7b20: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
7b30: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
7b40: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
7b50: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
7b60: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
7b70: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
7b80: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
7b90: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
7ba0: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
7bb0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
7bc0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
7bd0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
7be0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
7bf0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
7c00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7c10: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
7c20: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
7c30: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
7c40: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
7c50: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
7c60: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
7c70: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
7c80: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
7c90: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
7ca0: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
7cb0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
7cc0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
7cd0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
7ce0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
7cf0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
7d00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
7d10: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
7d20: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
7d30: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
7d40: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7d50: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
7d60: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
7d70: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
7d80: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
7d90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
7da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
7db0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
7dc0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
7dd0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
7de0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
7df0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
7e00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
7e10: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
7e20: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
7e30: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
7e40: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
7e50: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
7e60: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
7e70: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
7e80: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
7e90: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
7ea0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
7eb0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
7ec0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
7ed0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
7ee0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
7ef0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
7f00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
7f10: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
7f20: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
7f30: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
7f40: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
7f50: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
7f60: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
7f70: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
7f80: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
7f90: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
7fa0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
7fb0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
7fc0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
7fd0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
7fe0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
7ff0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8000: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
8010: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
8020: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
8030: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
8040: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
8050: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
8060: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
8070: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
8080: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
8090: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
80a0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
80b0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
80c0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
80d0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
80e0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
80f0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
8100: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
8110: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
8120: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
8130: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
8140: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
8150: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
8160: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
8170: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
8180: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
8190: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
81a0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
81b0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
81c0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
81d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
81e0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
81f0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
8200: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
8210: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8220: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
8230: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
8240: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8250: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
8260: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
8270: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
8280: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
8290: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
82a0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
82b0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
82c0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
82d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
82e0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
82f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8300: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8310: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
8320: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
8330: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
8340: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
8350: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
8360: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
8370: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
8380: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
8390: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
83a0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
83b0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
83c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
83d0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
83e0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
83f0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
8400: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
8410: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
8420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
8430: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
8440: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
8450: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
8460: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8470: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
8480: 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73  t close [databas
8490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
84a0: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
84b0: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
84c0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
84d0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
84e0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
84f0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
8500: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8510: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
8520: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
8530: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
8540: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
8550: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
8560: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
8570: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
8580: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
8590: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
85a0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
85b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
85c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
85d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
85e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
85f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
8600: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
8610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
8630: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
8640: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
8650: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
8660: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
8670: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
8680: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
8690: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
86a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
86b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
86c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
86d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
86e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
86f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8700: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
8710: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
8720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8730: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
8740: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
8750: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
8760: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
8770: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
8780: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
8790: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
87a0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
87b0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
87c0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
87d0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
87e0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
87f0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
8800: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
8810: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
8820: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
8830: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8840: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8850: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
8860: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
8870: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
8880: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8890: 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c   codes],.** [sql
88a0: 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
88b0: 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45  flict()] [SQLITE
88c0: 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75  _ROLLBACK | resu
88d0: 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64  lt codes]..*/.#d
88e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
88f0: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
8900: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
8910: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
8920: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
8930: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
8940: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
8950: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
8960: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
8970: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
8980: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
8990: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
89a0: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
89b0: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
89c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
89d0: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
89e0: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
89f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
8a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
8a10: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
8a20: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
8a30: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
8a40: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
8a50: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
8a60: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
8a70: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
8a80: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
8a90: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
8aa0: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
8ab0: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
8ac0: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
8ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ae0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
8af0: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
8b00: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
8b10: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8b20: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
8b30: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
8b40: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
8b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b60: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
8b70: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
8b80: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
8b90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
8ba0: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
8bb0: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
8bc0: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
8bd0: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
8be0: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
8bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8c00: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
8c10: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8c20: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
8c30: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
8c40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
8c50: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
8c60: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
8c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c80: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
8c90: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
8ca0: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
8cb0: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
8cc0: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
8cd0: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
8ce0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
8cf0: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
8d00: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
8d10: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
8d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d30: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
8d40: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
8d50: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
8d60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d70: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
8d80: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
8d90: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
8db0: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
8dd0: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
8de0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
8df0: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
8e00: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
8e10: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
8e20: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
8e30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8e40: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
8e50: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
8e60: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
8e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
8e80: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
8e90: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
8ea0: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
8eb0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
8ec0: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
8ed0: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
8ee0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
8ef0: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
8f00: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
8f10: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
8f20: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
8f30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8f40: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
8f50: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
8f60: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
8f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
8f80: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
8f90: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
8fa0: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
8fb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8fc0: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
8fd0: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
8fe0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8ff0: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
9000: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
9010: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
9020: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
9030: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
9040: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9060: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
9070: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
9080: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
9090: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
90a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
90b0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
90c0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
90d0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
90e0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
90f0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
9100: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
9110: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
9120: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
9130: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
9140: 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78   error code} {ex
9150: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
9160: 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
9170: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9180: 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  t code} {extende
9190: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a  d result codes}.
91a0: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
91b0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
91c0: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
91d0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
91e0: 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72  ne of 26 integer
91f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c  .** [SQLITE_OK |
9200: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
9210: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
9220: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
9230: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
9240: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
9250: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
9260: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
9270: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
9280: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
9290: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
92a0: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
92b0: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
92c0: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
92d0: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
92e0: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
92f0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
9300: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
9310: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
9320: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
9330: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
9340: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
9350: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
9360: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
9370: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20  out errors. The 
9380: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
9390: 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65  codes are enable
93a0: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
93b0: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
93c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
93d0: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
93e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
93f0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
9400: 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f  )] API..**.** So
9410: 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61  me of the availa
9420: 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  ble extended res
9430: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69  ult codes are li
9440: 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e  sted here..** On
9450: 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65  e may expect the
9460: 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e   number of exten
9470: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9480: 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a   will be expand.
9490: 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53  ** over time.  S
94a0: 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65  oftware that use
94b0: 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  s extended resul
94c0: 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65  t codes should e
94d0: 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20  xpect.** to see 
94e0: 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73  new result codes
94f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
9500: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
9510: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
9520: 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77  OK result code w
9530: 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74  ill never be ext
9540: 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20  ended.  It will 
9550: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61  always.** be exa
9560: 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64  ctly zero..*/.#d
9570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9580: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
9590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
95a0: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
95b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
95c0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
95d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
95e0: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
95f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9600: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
9610: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9620: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
9630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9640: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
9650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9660: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
9670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
9680: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
9690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
96a0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
96b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
96c0: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
96d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
96e0: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
96f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
9700: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
9710: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9720: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
9730: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
9740: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
9750: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
9760: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9770: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
9780: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
9790: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
97a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97b0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
97c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
97d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
97e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
97f0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
9800: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
9810: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
9820: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9830: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
9840: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9850: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
9860: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9870: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
9880: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9890: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
98a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98b0: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
98c0: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
98d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
98e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98f0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
9900: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9910: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
9920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9930: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
9940: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9950: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
9960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9970: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
9980: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
9990: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
99a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
99c0: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
99d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
99e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
99f0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
9a00: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
9a10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
9a20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a30: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
9a40: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
9a50: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
9a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9a70: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
9a80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9a90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
9aa0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ab0: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
9ac0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
9ad0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
9ae0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9af0: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
9b00: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
9b10: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
9b20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9b30: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
9b40: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
9b50: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
9b60: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9b70: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e  QLITE_CANTOPEN_N
9b80: 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53  OTEMPDIR      (S
9b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
9ba0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
9bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
9bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
9be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
9bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
9c00: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
9c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
9c20: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
9c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9c40: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
9c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
9c60: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f  NLY | (2<<8))../
9c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
9c80: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
9c90: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
9ca0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
9cb0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
9cc0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
9cd0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
9ce0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
9cf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
9d00: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
9d10: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
9d20: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
9d30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9d40: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
9d50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9d60: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
9d70: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
9d80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9d90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9da0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
9db0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
9dc0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
9dd0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9de0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9df0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9e00: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
9e10: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
9e20: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9e30: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
9e50: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
9e60: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
9e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
9e90: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
9ea0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
9eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
9ed0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
9ee0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
9ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
9f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
9f20: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
9f30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
9f40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
9f50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
9f60: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
9f70: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
9f80: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9f90: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
9fa0: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
9fb0: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
9fc0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
9fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
9fe0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
9ff0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
a000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
a020: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
a030: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
a040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
a060: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
a070: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
a080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
a0a0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
a0b0: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
a0c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a0d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
a0e0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
a0f0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
a100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
a110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
a120: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
a130: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
a140: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a150: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a160: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
a170: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
a180: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
a190: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a1b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
a1c0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
a1d0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
a1e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a1f0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a200: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
a210: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
a220: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
a230: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
a240: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
a250: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
a260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
a270: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
a280: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
a290: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a2b0: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
a2c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
a2d0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
a2e0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
a2f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a300: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
a310: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
a320: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
a330: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
a340: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
a350: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
a360: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
a370: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
a380: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
a390: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
a3a0: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
a3b0: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
a3c0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
a3d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a3e0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
a3f0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
a400: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
a410: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
a420: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
a430: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
a440: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a450: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a460: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
a470: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
a480: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
a490: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
a4a0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
a4b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
a4c0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
a4d0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
a4e0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
a4f0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
a500: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
a510: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
a520: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
a530: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
a540: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
a550: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
a560: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
a570: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
a580: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
a590: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
a5a0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
a5b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a5c0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
a5d0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
a5e0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
a5f0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
a600: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
a610: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
a620: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
a630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a640: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
a650: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a660: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
a670: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a680: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
a690: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
a6a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
a6b0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
a6c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
a6d0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
a6e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
a6f0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
a700: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
a710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
a720: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
a730: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a740: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
a750: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
a760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a770: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
a780: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a790: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
a7a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
a7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a7c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
a7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
a7e0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
a7f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a800: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
a810: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
a820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
a830: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a840: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a850: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
a860: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a870: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
a880: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
a8a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
a8b0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
a8c0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
a8d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
a8e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
a8f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
a900: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
a910: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
a920: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
a930: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
a940: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
a950: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a960: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
a970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a980: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
a990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a9a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
a9b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a9c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
a9d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
a9e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
a9f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
aa00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
aa10: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
aa20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa30: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
aa40: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
aa50: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
aa60: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
aa70: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
aa80: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
aa90: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
aaa0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
aab0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
aac0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
aad0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
aae0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
aaf0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
ab00: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
ab10: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
ab20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
ab30: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
ab40: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
ab50: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
ab60: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
ab70: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
ab80: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
ab90: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
aba0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
abb0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
abc0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
abd0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
abe0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
abf0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
ac00: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
ac10: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
ac20: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
ac30: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
ac40: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
ac50: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
ac60: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
ac70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
ac80: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
ac90: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
aca0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
acb0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
acc0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
acd0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
ace0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
acf0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
ad00: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
ad10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
ad20: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
ad30: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
ad40: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
ad50: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
ad60: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
ad70: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
ad80: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
ad90: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
ada0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
adb0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
adc0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
add0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
ade0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
adf0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
ae00: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
ae10: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
ae20: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
ae30: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
ae40: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
ae50: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
ae60: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
ae70: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
ae80: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
ae90: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
aea0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
aeb0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
aec0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
aed0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
aee0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
aef0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
af00: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
af10: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
af20: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
af30: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
af40: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
af50: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
af60: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
af70: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
af80: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
af90: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
afa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
afb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
afc0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
afd0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
afe0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
aff0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
b000: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
b010: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
b020: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
b030: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
b040: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
b050: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
b060: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
b070: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
b080: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
b090: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
b0a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
b0b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
b0c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
b0d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
b0e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
b0f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
b100: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
b110: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
b120: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b130: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
b140: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
b150: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
b160: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
b170: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
b180: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
b190: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
b1a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
b1b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
b1c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
b1d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b1e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
b1f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
b200: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
b210: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b220: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b230: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
b240: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
b250: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
b260: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
b270: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
b280: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
b290: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
b2a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
b2b0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
b2c0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
b2d0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
b2e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
b2f0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
b300: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
b310: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
b320: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
b330: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
b340: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
b350: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
b360: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
b370: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
b380: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
b390: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b3a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
b3b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
b3c0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
b3d0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
b3e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
b3f0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
b400: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
b410: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
b420: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
b430: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
b440: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
b450: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
b460: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
b470: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
b480: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
b490: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
b4a0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
b4b0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
b4c0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
b4d0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
b4e0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
b4f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
b500: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
b510: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
b520: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
b530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
b540: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
b550: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
b560: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
b570: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
b580: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
b590: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
b5a0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
b5b0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
b5c0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
b5d0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
b5e0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
b5f0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
b600: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
b610: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
b620: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
b630: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
b640: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
b650: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
b660: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
b670: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
b680: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
b690: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
b6a0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
b6b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
b6c0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
b6d0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
b6e0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
b6f0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b700: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
b710: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
b720: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
b730: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
b740: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
b750: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
b760: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
b770: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
b780: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
b790: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
b7a0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
b7b0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
b7c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
b7d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
b7e0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
b7f0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
b800: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
b810: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
b820: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
b830: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
b840: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
b850: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
b860: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
b870: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
b880: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
b890: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
b8a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
b8b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
b8c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
b8d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
b8e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
b8f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
b900: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
b910: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
b920: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
b930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
b940: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
b950: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
b960: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
b970: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
b980: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
b990: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
b9a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
b9b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
b9c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
b9d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
b9e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
b9f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
ba00: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
ba10: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
ba20: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
ba30: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
ba40: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
ba50: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
ba60: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
ba70: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
ba80: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
ba90: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
baa0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
bab0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
bac0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
bad0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
bae0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
baf0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
bb00: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
bb10: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
bb20: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
bb30: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
bb40: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
bb50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
bb60: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
bb70: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
bb80: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
bb90: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
bba0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
bbb0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
bbc0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
bbd0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
bbe0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
bbf0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
bc00: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
bc10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
bc20: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
bc30: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
bc40: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
bc50: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
bc60: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
bc70: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
bc80: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
bc90: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bca0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
bcb0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
bcc0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
bcd0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
bce0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
bcf0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
bd00: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
bd10: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
bd20: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
bd30: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
bd40: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
bd50: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
bd60: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
bd70: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
bd80: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
bd90: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
bda0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
bdb0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
bdc0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
bdd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
bde0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
bdf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
be00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
be20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
be40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
be60: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
be80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
be90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
bea0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
beb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
bec0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
bed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
bee0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
bef0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
bf00: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
bf10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
bf20: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
bf30: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
bf40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
bf50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
bf60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
bf70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
bf80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
bf90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
bfa0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
bfb0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
bfc0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
bfd0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
bfe0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
bff0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
c000: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
c010: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
c020: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
c030: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
c040: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
c050: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
c060: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
c070: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c080: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
c090: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
c0a0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
c0b0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
c0c0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
c0d0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
c0e0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
c0f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
c100: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
c110: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
c120: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
c130: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
c140: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
c150: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
c160: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
c170: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
c180: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
c190: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
c1a0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
c1b0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
c1c0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
c1d0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
c1e0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
c1f0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
c200: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
c210: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
c220: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
c230: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
c240: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
c250: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
c260: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
c270: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
c280: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
c290: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c2a0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
c2b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
c2c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
c2d0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
c2e0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
c2f0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
c300: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
c310: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
c320: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
c330: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
c340: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
c350: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
c360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
c370: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
c380: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
c390: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
c3a0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
c3b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
c3c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
c3d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
c3e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c3f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
c400: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
c410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
c420: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
c430: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
c440: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
c450: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
c460: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
c470: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
c480: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
c490: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
c4a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
c4b0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
c4c0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
c4d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
c4e0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
c4f0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
c500: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
c510: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
c520: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
c530: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
c540: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
c550: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c560: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
c570: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
c580: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
c590: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
c5a0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
c5b0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
c5c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
c5d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c5e0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
c5f0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
c600: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
c610: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
c620: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
c630: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
c640: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
c650: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
c660: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c670: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
c680: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
c690: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
c6a0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
c6b0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
c6c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
c6d0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
c6e0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
c6f0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
c700: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
c710: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
c720: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
c730: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
c740: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
c750: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c760: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
c770: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
c780: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
c790: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
c7b0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
c7c0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
c7d0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
c7e0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
c7f0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
c800: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
c810: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
c820: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
c830: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
c840: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
c850: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
c860: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
c870: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
c880: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
c890: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
c8a0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
c8b0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
c8c0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
c8d0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
c8e0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
c8f0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
c900: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
c910: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
c920: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
c930: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
c940: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
c950: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c960: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
c970: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
c980: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
c990: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
c9a0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
c9b0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
c9c0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
c9d0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
c9e0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
c9f0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
ca00: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
ca10: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
ca20: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
ca30: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
ca40: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
ca50: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
ca60: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
ca70: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
ca80: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
ca90: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
caa0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
cab0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
cac0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
cad0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ster..**.** The 
cae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
caf0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
cb00: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
cb10: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
cb20: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
cb30: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
cb40: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
cb50: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
cb60: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
cb70: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
cb80: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
cb90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cba0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
cbb0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
cbc0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
cbd0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
cbe0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
cbf0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
cc00: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
cc10: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
cc20: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
cc30: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
cc40: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
cc50: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
cc60: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
cc70: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
cc80: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
cc90: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
cca0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
ccb0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
ccc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
ccd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
cce0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
ccf0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
cd00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
cd10: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
cd20: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
cd30: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
cd40: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
cd50: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
cd60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
cd70: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
cd80: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
cd90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
cda0: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
cdb0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
cdc0: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
cdd0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
cde0: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
cdf0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
ce00: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
ce10: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
ce20: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
ce30: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
ce40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
ce50: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
ce60: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
ce70: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
ce80: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
ce90: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
cea0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
ceb0: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
cec0: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
ced0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
cee0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
cef0: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
cf00: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
cf10: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
cf20: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
cf30: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
cf40: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
cf50: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
cf60: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
cf70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
cf80: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
cf90: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
cfa0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
cfb0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
cfc0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
cfd0: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
cfe0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
cff0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  .  .**.** ^The [
d000: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
d010: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
d020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
d030: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
d040: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
d050: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
d060: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
d070: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
d080: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
d090: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
d0a0: 65 72 20 74 6f 20 77 6f 72 6b 20 74 6f 20 70 72  er to work to pr
d0b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
d0c0: 20 61 67 61 69 6e 73 74 0a 2a 2a 20 61 6e 74 69   against.** anti
d0d0: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
d0e0: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
d0f0: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
d100: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
d110: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
d120: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
d130: 74 65 20 6f 70 65 72 74 69 6f 6e 73 20 75 70 20  te opertions up 
d140: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
d150: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
d160: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
d170: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
d180: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
d190: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
d1a0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
d1b0: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
d1c0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
d1d0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
d1e0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
d1f0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 6f 73  code allows thos
d200: 65 20 74 6f 20 76 61 6c 75 65 73 20 28 31 30 20  e to values (10 
d210: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
d220: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
d230: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
d240: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
d250: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
d260: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
d270: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
d280: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
d290: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
d2a0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
d2b0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
d2c0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
d2d0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
d2e0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
d2f0: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
d300: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d310: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
d320: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
d330: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
d340: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
d350: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
d360: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
d370: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
d380: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
d390: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
d3a0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
d3b0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
d3c0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
d3d0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
d3e0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
d3f0: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
d400: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
d410: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 0a 2a  s ignored..** .*
d420: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d430: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
d440: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
d450: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
d460: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
d470: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
d480: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
d490: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
d4a0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
d4b0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
d4c0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
d4d0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
d4e0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
d4f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
d500: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
d510: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d520: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
d530: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
d540: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
d550: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
d560: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
d570: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
d580: 52 45 54 52 59 20 20 20 39 0a 0a 2f 2a 0a 2a 2a  RETRY   9../*.**
d590: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
d5a0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
d5b0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
d5c0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
d5d0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
d5e0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
d5f0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
d600: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
d610: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
d620: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
d630: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
d640: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
d650: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
d660: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
d670: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
d680: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
d690: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d6a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
d6b0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
d6c0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
d6d0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
d6e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d6f0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
d700: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
d710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d720: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
d730: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
d740: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
d750: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
d760: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
d770: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
d780: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
d790: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
d7a0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
d7b0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
d7c0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
d7d0: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
d7e0: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
d7f0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
d800: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
d810: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
d820: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
d830: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
d840: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
d850: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
d860: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
d870: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
d880: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
d890: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
d8a0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
d8b0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
d8c0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
d8d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
d8e0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
d8f0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
d900: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
d910: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
d920: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
d930: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
d940: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
d950: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
d960: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
d970: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
d980: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
d990: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
d9a0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
d9b0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
d9c0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
d9d0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
d9e0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
d9f0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
da00: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
da10: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
da20: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
da30: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
da40: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
da50: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
da60: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
da70: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
da80: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
da90: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
daa0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
dab0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
dac0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
dad0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
dae0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
daf0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
db00: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
db10: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
db20: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
db30: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
db40: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
db50: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
db60: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
db70: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
db80: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
db90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
dba0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
dbb0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
dbc0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
dbd0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
dbe0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
dbf0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
dc00: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
dc10: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
dc20: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
dc30: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
dc40: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
dc50: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
dc60: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
dc70: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
dc80: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
dc90: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
dca0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
dcb0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
dcc0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
dcd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
dce0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
dcf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
dd00: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
dd10: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
dd20: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
dd30: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
dd40: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
dd50: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
dd60: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dd70: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
dd80: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
dd90: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
dda0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
ddb0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
ddc0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
ddd0: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
dde0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
ddf0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
de00: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
de10: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
de20: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
de30: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
de40: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
de50: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
de60: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
de70: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
de80: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
de90: 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68   than.** 10 alph
dea0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
deb0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
dec0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
ded0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
dee0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
def0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
df00: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
df10: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
df20: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
df30: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
df40: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
df50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
df60: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
df70: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
df80: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
df90: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
dfa0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
dfb0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
dfc0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
dfd0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
dfe0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
dff0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
e000: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
e010: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
e020: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
e030: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
e040: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
e050: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
e060: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
e070: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
e080: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
e090: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
e0a0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
e0b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
e0c0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
e0d0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
e0e0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
e0f0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
e100: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
e110: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
e120: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
e130: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
e140: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
e150: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
e160: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
e170: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
e180: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
e190: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
e1a0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
e1b0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
e1c0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
e1d0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
e1e0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
e1f0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
e200: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
e210: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
e220: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
e230: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
e240: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
e250: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
e260: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
e270: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
e280: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
e290: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
e2a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
e2b0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
e2c0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e2d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e2e0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
e2f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e300: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
e310: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e320: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
e330: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e340: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
e350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e360: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
e370: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
e380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
e390: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e3b0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
e3c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e3d0: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
e3e0: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
e3f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
e400: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
e410: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
e420: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
e430: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
e440: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
e450: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
e460: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
e470: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
e480: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
e490: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
e4a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
e4b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
e4c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
e4d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
e4e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
e4f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
e500: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
e510: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
e520: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
e530: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
e540: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
e550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
e560: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
e570: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
e580: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
e590: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
e5a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
e5b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
e5c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
e5d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
e5e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
e5f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
e600: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
e610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e630: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
e640: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
e650: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
e660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
e670: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
e680: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e690: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
e6a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
e6b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e6c0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
e6d0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
e6e0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
e6f0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
e700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e710: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
e720: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
e730: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
e740: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
e750: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
e760: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
e770: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
e780: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
e790: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e7a0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
e7b0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
e7c0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
e7d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
e7e0: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
e7f0: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
e800: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
e810: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
e820: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
e830: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
e840: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
e850: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
e860: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
e870: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
e880: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
e890: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
e8a0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
e8b0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
e8c0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
e8d0: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
e8e0: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
e8f0: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
e900: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
e910: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
e920: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
e930: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
e940: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
e950: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
e960: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
e970: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
e980: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
e990: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
e9a0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
e9b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
e9c0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
e9d0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
e9e0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
e9f0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
ea00: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
ea10: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
ea20: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
ea30: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
ea40: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
ea50: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
ea60: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
ea70: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
ea80: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
ea90: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
eaa0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
eab0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
eac0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
ead0: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
eae0: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
eaf0: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
eb00: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
eb10: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
eb20: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
eb30: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
eb40: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
eb50: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
eb60: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
eb70: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
eb80: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
eb90: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
eba0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
ebb0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
ebc0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
ebd0: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
ebe0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
ebf0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
ec00: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
ec10: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
ec20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ec30: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
ec40: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
ec50: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
ec60: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
ec70: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
ec80: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
ec90: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
eca0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
ecb0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
ecc0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
ecd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
ece0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
ecf0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
ed00: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
ed10: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
ed20: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
ed30: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
ed40: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
ed50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
ed60: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
ed70: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
ed80: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
ed90: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
eda0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
edb0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
edc0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
edd0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
ede0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
edf0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
ee00: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
ee10: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
ee20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
ee30: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
ee40: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
ee50: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
ee60: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
ee70: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
ee80: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
ee90: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
eea0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
eeb0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
eec0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
eed0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
eee0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
eef0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
ef00: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
ef10: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
ef20: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
ef30: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
ef40: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
ef50: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
ef60: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
ef70: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
ef80: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
ef90: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
efa0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
efb0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
efc0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
efd0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
efe0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
eff0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
f000: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
f010: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
f020: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
f030: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
f040: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
f050: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
f060: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
f070: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
f080: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
f090: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
f0a0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
f0b0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
f0c0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
f0d0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
f0e0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
f0f0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
f100: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
f110: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
f120: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
f130: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
f140: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
f150: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
f160: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
f170: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
f180: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
f190: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
f1a0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
f1b0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
f1c0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
f1d0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
f1e0: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
f1f0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
f200: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
f210: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
f220: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
f230: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
f240: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
f250: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
f260: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
f270: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
f280: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
f290: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
f2a0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
f2b0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
f2c0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
f2d0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
f2e0: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
f2f0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
f300: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
f310: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
f320: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
f330: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
f340: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
f350: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
f360: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
f370: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
f380: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
f390: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
f3a0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
f3b0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
f3c0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
f3d0: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
f3e0: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
f3f0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
f400: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
f410: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
f420: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
f430: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
f440: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
f450: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
f460: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
f470: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
f480: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
f490: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
f4a0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
f4b0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
f4c0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
f4d0: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
f4e0: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
f4f0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
f500: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
f510: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
f520: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
f530: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
f540: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
f550: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
f560: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
f570: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
f580: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
f590: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
f5a0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
f5b0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
f5c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
f5d0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
f5e0: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
f5f0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
f600: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
f610: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
f620: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
f630: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
f640: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
f650: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
f660: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
f670: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
f680: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
f690: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
f6a0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
f6b0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
f6c0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
f6d0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
f6e0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
f6f0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
f700: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
f710: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
f720: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
f730: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
f740: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
f750: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
f760: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
f770: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
f780: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
f790: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
f7a0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
f7b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
f7c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
f7d0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
f7e0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
f7f0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
f800: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
f810: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
f820: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f830: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f840: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
f850: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
f860: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f870: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
f880: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
f890: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
f8a0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
f8b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
f8c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
f8d0: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
f8e0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
f8f0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
f900: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
f910: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
f920: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
f930: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
f940: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
f950: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
f960: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
f970: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
f980: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
f990: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
f9a0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
f9b0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
f9c0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
f9d0: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
f9e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f9f0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
fa00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
fa10: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
fa20: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
fa30: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
fa40: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
fa50: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
fa60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
fa70: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
fa80: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
fa90: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
faa0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
fab0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
fac0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
fad0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
fae0: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
faf0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
fb00: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
fb10: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
fb20: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
fb30: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
fb40: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
fb50: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
fb60: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
fb70: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
fb80: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
fb90: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
fba0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
fbb0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
fbc0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
fbd0: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
fbe0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
fbf0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fc00: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fc10: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
fc20: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
fc30: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
fc40: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
fc50: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fc60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fc70: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
fc80: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
fc90: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
fca0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fcb0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
fcc0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fcd0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fce0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
fcf0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
fd00: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
fd10: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
fd20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
fd30: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
fd40: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
fd50: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
fd60: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
fd70: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
fd80: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
fd90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
fda0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
fdb0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
fdc0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
fdd0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
fde0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
fdf0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
fe00: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
fe10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
fe20: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
fe30: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
fe40: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
fe50: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
fe60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
fe70: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
fe80: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
fe90: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
fea0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
feb0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
fec0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
fed0: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
fee0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
fef0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
ff00: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ff10: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
ff20: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
ff30: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
ff40: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
ff50: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
ff60: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
ff70: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
ff80: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
ff90: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
ffa0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
ffb0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
ffc0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ffd0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
ffe0: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
fff0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
10000 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
10010 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
10020 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
10030 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
10040 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
10050 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
10060 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
10070 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10080 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
10090 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
100a0 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
100b0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
100c0 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
100d0 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
100e0 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
100f0 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
10100 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
10110 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
10120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10130 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
10140 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
10150 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10160 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
10170 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
10180 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
10190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
101a0 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
101b0 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
101c0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
101d0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
101e0 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
101f0 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
10200 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
10210 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
10220 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
10230 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
10240 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
10250 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
10260 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10270 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
10280 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
10290 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
102a0 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
102b0 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
102c0 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
102d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
102e0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
102f0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
10300 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
10310 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
10320 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10330 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
10340 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
10350 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10360 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10370 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10380 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10390 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
103a0 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
103b0 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
103c0 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
103d0 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
103e0 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
103f0 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
10400 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
10410 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
10420 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
10430 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
10440 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
10450 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
10460 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
10470 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
10480 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
10490 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
104a0 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
104b0 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
104c0 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
104d0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
104e0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
104f0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
10500 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
10510 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
10520 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10530 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
10540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10550 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
10560 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
10570 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
10580 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
10590 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
105a0 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
105b0 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
105c0 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
105d0 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
105e0 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
105f0 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
10600 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
10610 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
10620 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
10630 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
10640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10650 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
10660 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
10670 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
10680 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
10690 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
106a0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106b0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
106c0 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
106d0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
106e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
106f0 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
10700 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
10710 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
10720 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
10730 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
10740 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
10750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
10760 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
10770 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
10780 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
10790 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
107a0 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
107b0 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
107c0 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
107d0 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
107e0 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
107f0 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
10800 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
10810 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
10820 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10830 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
10840 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
10850 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
10860 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
10870 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10880 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
10890 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
108a0 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
108b0 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
108c0 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
108d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
108e0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
108f0 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
10900 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
10910 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
10920 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
10930 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
10940 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
10950 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
10960 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
10970 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
10980 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
10990 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
109a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
109b0 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
109c0 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
109d0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
109e0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
109f0 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
10a00 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
10a10 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
10a20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
10a30 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
10a40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10a50 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
10a60 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
10a70 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
10a80 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
10a90 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
10aa0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
10ab0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
10ac0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10ae0 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
10af0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10b00 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
10b10 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
10b20 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
10b30 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
10b40 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
10b50 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
10b60 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
10b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
10b80 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
10b90 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
10ba0 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
10bb0 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
10bc0 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
10bd0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
10be0 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
10bf0 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
10c00 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
10c10 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
10c20 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
10c30 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
10c40 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
10c50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
10c60 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
10c70 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
10c80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
10c90 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10ca0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
10cb0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
10cc0 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
10cd0 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
10ce0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10cf0 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
10d00 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
10d10 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
10d20 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
10d30 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
10d40 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
10d50 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
10d60 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
10d70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
10d80 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
10d90 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
10da0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10db0 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
10dc0 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
10dd0 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
10de0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
10df0 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
10e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
10e10 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
10e20 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
10e30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10e40 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
10e50 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
10e60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
10e70 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
10e80 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
10e90 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10ea0 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
10eb0 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
10ec0 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
10ed0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
10ee0 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
10ef0 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
10f00 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
10f10 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
10f20 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10f30 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
10f40 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
10f50 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
10f60 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
10f70 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
10f80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
10f90 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
10fa0 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
10fb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
10fc0 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
10fd0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
10fe0 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
10ff0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11000 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11010 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
11020 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
11030 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
11040 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
11050 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
11060 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11070 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
11080 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
11090 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
110a0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
110b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
110c0 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
110d0 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
110e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
110f0 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
11100 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
11110 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11120 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
11130 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
11140 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
11150 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
11160 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
11170 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
11180 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
11190 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
111a0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
111b0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
111c0 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
111d0 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
111e0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
111f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11200 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
11210 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
11220 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
11230 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
11240 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
11250 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
11260 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
11270 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
11280 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
11290 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
112a0 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
112b0 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
112c0 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
112d0 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
112e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
112f0 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
11300 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
11310 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
11320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
11330 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
11340 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11350 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
11360 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
11370 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
11380 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11390 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
113a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
113b0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
113c0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
113d0 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
113e0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
11400 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
11410 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
11420 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
11430 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11440 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
11450 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
11460 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
11470 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
11480 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
11490 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
114a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
114b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
114c0 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
114d0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
114e0 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
114f0 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
11500 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
11510 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
11520 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
11530 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
11540 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
11550 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
11560 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
11570 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
11580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11590 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
115a0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
115b0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
115c0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
115d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
115e0 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
115f0 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
11600 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
11610 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11620 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
11630 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
11640 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
11650 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
11660 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
11670 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
11680 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c   failure..*/.SQL
11690 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
116a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
116b0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
116c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75   int sqlite3_shu
116d0 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  tdown(void);.SQL
116e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
116f0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
11700 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
11710 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
11720 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
11730 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11740 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
11750 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
11760 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11770 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11780 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
11790 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
117a0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
117b0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
117c0 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
117d0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
117e0 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
117f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
11800 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
11810 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
11820 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
11830 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
11840 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
11850 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
11860 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
11870 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
11880 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
11890 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
118a0 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
118b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
118c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
118d0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
118e0 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
118f0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
11900 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
11910 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
11920 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
11930 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
11940 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
11950 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11960 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
11970 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
11980 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
11990 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
119a0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
119b0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
119c0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
119d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
119e0 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
119f0 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
11a00 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
11a10 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
11a20 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
11a30 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
11a40 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
11a50 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
11a60 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
11a70 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
11a80 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
11a90 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
11aa0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
11ab0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
11ac0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
11ad0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
11ae0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
11af0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
11b00 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
11b10 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
11b20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11b30 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
11b40 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
11b50 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
11b60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
11b70 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
11b80 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
11b90 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
11ba0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
11bb0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
11bc0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
11bd0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
11be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11bf0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
11c00 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
11c10 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
11c20 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c30 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
11c40 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
11c50 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
11c60 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
11c70 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
11c80 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
11c90 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
11ca0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
11cb0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
11cc0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11cd0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
11ce0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
11cf0 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
11d00 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
11d10 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
11d20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11d30 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
11d40 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11d50 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
11d60 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
11d70 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
11d80 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
11d90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
11da0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
11db0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
11dc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11dd0 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
11de0 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
11df0 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
11e00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11e10 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
11e20 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
11e30 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
11e40 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
11e50 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
11e60 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
11e70 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
11e80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11e90 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
11ea0 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
11eb0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
11ec0 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
11ed0 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
11ee0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
11ef0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
11f00 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
11f10 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
11f20 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
11f30 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
11f40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
11f50 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
11f60 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
11f70 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
11f80 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
11f90 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
11fa0 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
11fb0 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
11fc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
11fd0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11fe0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
11ff0 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
12000 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
12010 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
12020 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
12030 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12040 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
12050 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
12060 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
12070 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
12080 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12090 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
120a0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
120b0 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
120c0 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
120d0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
120e0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
120f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
12100 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
12110 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
12120 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12130 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
12140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
12150 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
12160 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
12170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12180 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
12190 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
121a0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
121b0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
121c0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
121d0 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
121e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
121f0 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
12200 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
12210 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
12220 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
12230 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
12240 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
12250 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
12260 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
12270 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
12280 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
12290 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
122a0 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
122b0 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
122c0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
122d0 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
122e0 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
122f0 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
12300 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
12310 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
12320 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
12330 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
12340 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
12350 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
12360 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
12370 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
12380 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
12390 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
123a0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
123b0 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
123c0 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
123d0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
123e0 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
123f0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
12400 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
12410 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
12420 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
12430 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
12440 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
12450 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
12460 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
12470 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
12480 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
12490 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61  ** The xMalloc a
124a0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
124b0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
124c0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20  the.** malloc() 
124d0 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
124e0 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
124f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
12500 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f  ..** The xReallo
12510 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f  c method must wo
12520 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28  rk like realloc(
12530 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  ) from the stand
12540 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a  ard C library.**
12550 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74   with the except
12560 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20  ion that if the 
12570 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12580 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a  to xRealloc is z
12590 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ero,.** xRealloc
125a0 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70   must be a no-op
125b0 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70   - it must not p
125c0 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63  erform any alloc
125d0 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c  ation or.** deal
125e0 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69  location.  ^SQLi
125f0 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
12600 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
12610 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
12620 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
12630 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
12640 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
12650 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
12660 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73   And so in cases
12670 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20   where xRoundup 
12680 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
12690 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
126a0 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61  ,.** xRealloc ca
126b0 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c  n perform exactl
126c0 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72  y as the standar
126d0 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f  d library reallo
126e0 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c  c() and.** still
126f0 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63   be in complianc
12700 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63  e with this spec
12710 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ification..**.**
12720 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
12730 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
12740 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
12750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
12760 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
12770 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
12780 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
12790 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
127a0 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
127b0 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
127c0 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
127d0 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
127e0 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
127f0 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
12800 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
12810 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
12820 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
12830 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
12840 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
12850 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
12860 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
12870 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12880 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
12890 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
128a0 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
128b0 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
128c0 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
128d0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
128e0 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
128f0 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
12900 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
12910 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
12920 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
12930 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
12940 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12950 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
12960 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
12970 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
12980 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
12990 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
129a0 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
129b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
129c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
129d0 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
129e0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
129f0 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
12a00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
12a10 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
12a20 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
12a30 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
12a40 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
12a50 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
12a60 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
12a70 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
12a80 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
12a90 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
12aa0 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
12ab0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
12ac0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
12ad0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
12ae0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
12af0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
12b00 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
12b10 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
12b20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12b30 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
12b40 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
12b50 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
12b60 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12b70 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
12b80 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
12b90 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
12ba0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
12bb0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
12bc0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
12bd0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
12be0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
12bf0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
12c00 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12c10 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
12c20 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
12c30 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
12c40 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
12c50 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
12c60 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
12c70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
12c80 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
12c90 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
12ca0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12cb0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
12cc0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12cd0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
12ce0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
12cf0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
12d00 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
12d10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
12d20 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
12d30 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
12d40 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12d50 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
12d60 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
12d70 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
12d80 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
12d90 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
12da0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
12db0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
12dc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
12dd0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
12de0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
12df0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
12e00 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
12e10 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
12e20 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
12e30 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
12e40 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12e50 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
12e60 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
12e70 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12e80 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12e90 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
12ea0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
12eb0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
12ec0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
12ed0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
12ee0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
12ef0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12f00 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
12f10 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
12f20 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
12f30 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12f40 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
12f50 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12f60 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
12f70 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
12f80 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12f90 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
12fa0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
12fb0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
12fc0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
12fd0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
12fe0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
12ff0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
13000 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13010 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13020 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13030 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13040 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13050 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13060 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13070 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13080 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13090 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
130a0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
130b0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
130c0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
130d0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
130e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
130f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13100 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
13110 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13120 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13130 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13140 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13150 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13160 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13170 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13180 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13190 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
131a0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
131b0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
131c0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
131d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
131e0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
131f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13200 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13210 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13220 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13230 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13240 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13250 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13260 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13270 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13280 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13290 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
132a0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
132b0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
132c0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
132d0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
132e0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
132f0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13300 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
13310 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
13320 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13330 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13340 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13350 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13360 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13370 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13380 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13390 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
133a0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
133b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
133c0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
133d0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
133e0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
133f0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
13400 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
13410 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
13420 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13430 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13440 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13450 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13460 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13470 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13480 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13490 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
134a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
134b0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
134c0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
134d0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
134e0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
134f0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
13500 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
13510 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
13520 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13530 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
13540 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13550 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13570 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13580 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13590 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
135a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
135b0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
135c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
135d0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
135e0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
135f0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13600 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
13610 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
13620 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
13630 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
13640 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
13650 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13660 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13670 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13680 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
136a0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
136b0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
136c0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
136d0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
136e0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
136f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13700 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
13710 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
13720 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
13730 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
13740 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
13750 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
13760 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
13770 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
13780 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
13790 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
137a0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
137b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
137c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
137d0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
137e0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
137f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13800 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13810 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13820 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13830 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13840 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
13850 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13860 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
13870 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
13880 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13890 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
138a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
138b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
138c0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
138d0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
138e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
138f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13900 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
13910 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13920 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
13930 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13940 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
13950 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13960 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13970 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13980 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13990 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
139a0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
139b0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
139c0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
139d0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
139e0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
139f0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
13a00 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
13a10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13a20 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
13a30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13a40 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
13a50 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
13a60 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
13a70 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
13a80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
13a90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13aa0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
13ab0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
13ac0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
13ad0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
13ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13af0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13b00 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
13b10 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
13b20 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
13b30 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
13b40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13b50 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
13b60 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
13b70 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
13b80 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
13b90 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
13ba0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
13bb0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13bc0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13bd0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13be0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13c00 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13c10 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13c20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
13c30 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
13c40 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
13c50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13c60 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
13c70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13c80 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
13c90 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13ca0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
13cb0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13cc0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13ce0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13cf0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
13d00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13d10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13d20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13d30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13d40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
13d50 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13d60 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13d70 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13d80 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13d90 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13da0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13db0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13dc0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13dd0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
13de0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
13df0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13e00 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13e10 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
13e20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
13e30 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
13e40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
13e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
13e60 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13e70 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
13e80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13e90 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
13ea0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13ec0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
13ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13ee0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13ef0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13f00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13f10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13f20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13f30 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13f40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
13f50 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
13f60 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
13f70 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13f80 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13f90 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13fa0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13fb0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
13fc0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
13fd0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13fe0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13ff0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14000 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14010 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14020 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14030 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14040 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14050 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14060 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14070 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
14080 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
14090 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
140a0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
140b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
140c0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
140d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
140e0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
140f0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
14100 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
14110 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
14120 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
14130 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
14140 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
14150 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14160 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
14170 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
14180 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14190 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
141a0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
141b0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
141c0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
141d0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
141e0 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
141f0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14200 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
14210 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
14220 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
14230 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
14240 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
14250 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
14260 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
14270 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
14280 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
14290 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
142a0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
142b0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
142c0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
142d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
142e0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
142f0 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
14300 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
14310 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
14320 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
14330 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14340 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14350 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14360 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
14370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14380 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
14390 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
143a0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
143b0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
143c0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
143d0 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
143e0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
143f0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
14400 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
14410 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
14420 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
14430 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
14440 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
14450 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
14460 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
14470 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
14480 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
14490 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
144a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
144b0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
144c0 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
144d0 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
144e0 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
144f0 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
14500 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
14510 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
14520 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
14530 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
14540 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
14550 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
14560 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
14570 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
14580 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
14590 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
145a0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
145b0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
145c0 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
145d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
145e0 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
145f0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
14600 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
14610 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
14620 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
14630 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
14640 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
14650 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
14660 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
14670 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
14680 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
14690 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
146a0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
146b0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
146c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
146d0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
146e0 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
146f0 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
14700 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14710 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14720 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
14730 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14740 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14750 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
14760 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14770 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
14780 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
14790 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
147a0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
147b0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
147c0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
147d0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
147e0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
147f0 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
14800 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
14810 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
14820 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
14830 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
14840 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
14850 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14860 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
14870 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14880 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
14890 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
148a0 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
148b0 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
148c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
148d0 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
148e0 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
148f0 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
14900 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
14910 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
14920 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
14930 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
14940 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
14950 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
14960 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
14970 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
14980 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
14990 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
149a0 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
149b0 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
149c0 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
149d0 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
149e0 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
149f0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
14a00 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
14a10 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
14a20 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
14a30 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
14a40 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
14a50 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
14a60 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
14a70 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
14a80 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
14a90 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
14aa0 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
14ab0 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
14ac0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14ad0 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
14ae0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
14af0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
14b00 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
14b10 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
14b20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
14b30 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14b40 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
14b50 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
14b60 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
14b70 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
14b80 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
14b90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
14ba0 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
14bb0 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
14bc0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
14bd0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
14be0 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
14bf0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
14c00 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
14c10 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
14c20 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
14c30 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
14c40 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
14c50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14c60 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14c70 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14c80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
14c90 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
14ca0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
14cb0 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
14cc0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
14cd0 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
14ce0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14d00 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
14d10 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
14d20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14d30 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
14d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14d50 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
14d60 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
14d70 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
14d80 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
14d90 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
14da0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14db0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
14dc0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
14dd0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14de0 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
14df0 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
14e00 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14e10 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
14e20 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
14e30 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
14e40 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
14e50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14e60 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
14e70 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
14e80 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
14e90 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
14ea0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
14eb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
14ec0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
14ed0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
14ee0 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
14ef0 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
14f00 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
14f10 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14f20 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
14f30 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
14f40 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
14f50 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
14f60 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
14f70 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
14f80 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
14f90 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
14fa0 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
14fb0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14fc0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
14fd0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
14fe0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
14ff0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
15000 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
15010 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
15020 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
15030 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
15040 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
15050 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  2^12. Reasonable
15060 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
15070 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15080 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
15090 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c  ^5 through 2^8.<
150a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
150b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
150c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
150d0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
150e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
150f0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15100 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15110 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
15120 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
15130 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15140 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15150 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15160 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
15170 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
15180 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
15190 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
151a0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
151b0 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
151c0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
151d0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
151e0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
151f0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
15200 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
15210 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15220 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
15230 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
15240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
15250 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
15260 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
15270 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
15280 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15290 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
152a0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
152b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
152c0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
152d0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
152e0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
152f0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
15300 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
15310 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
15320 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
15330 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15340 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
15350 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
15360 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
15370 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
15380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15390 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
153a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
153b0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
153c0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
153d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
153e0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
153f0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
15400 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
15410 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15420 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15430 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15440 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
15450 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
15460 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
15470 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
15480 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
15490 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
154a0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
154b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
154c0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
154d0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
154e0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
154f0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15500 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15510 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15520 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15530 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
15540 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
15550 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15560 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15570 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15580 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15590 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
155a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
155b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
155c0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
155d0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
155e0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
155f0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15600 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15610 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15620 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15630 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
15640 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15650 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
15660 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
15670 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15680 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15690 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
156a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
156b0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
156c0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
156d0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
156e0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
156f0 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
15700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15710 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
15720 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
15730 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
15740 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15750 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
15760 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
15770 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15780 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15790 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
157a0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
157b0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
157c0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
157d0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
157e0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
157f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
15800 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
15810 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
15820 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
15830 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
15840 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
15850 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15860 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
15870 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
15880 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
15890 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
158a0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
158b0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
158c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
158d0 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e  IG_PCACHE]] <dt>
158e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
158f0 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
15900 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
15910 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15920 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
15930 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
15940 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15950 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
15960 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
15970 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15980 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
15990 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
159a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
159b0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
159c0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
159d0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
159e0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
159f0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
15a00 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
15a10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15a20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15a30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15a40 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
15a50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15a60 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
15a70 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15a80 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
15a90 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
15aa0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
15ab0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
15ac0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
15ad0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
15ae0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
15af0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15b00 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15b10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15b20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15b30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15b40 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15b50 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
15b60 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
15b70 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
15b80 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
15b90 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
15ba0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
15bb0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
15bc0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
15bd0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
15be0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
15bf0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
15c00 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
15c10 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
15c20 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
15c30 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
15c40 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
15c50 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
15c60 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
15c70 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
15c80 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
15c90 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
15ca0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
15cb0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
15cc0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
15cd0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15ce0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
15cf0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
15d00 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
15d10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15d20 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
15d30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
15d40 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
15d50 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
15d60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
15d70 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
15d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
15d90 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
15da0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
15db0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
15dc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15dd0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
15de0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15df0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
15e00 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
15e10 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
15e20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15e30 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
15e40 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15e50 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
15e60 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
15e70 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
15e80 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
15e90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15ea0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
15eb0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
15ec0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
15ed0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
15ee0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
15ef0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
15f00 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15f10 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
15f20 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
15f30 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
15f40 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
15f50 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
15f60 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
15f70 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
15f80 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
15f90 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15fb0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
15fc0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
15fd0 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
15fe0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15ff0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
16000 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
16010 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
16020 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16030 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
16040 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
16050 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
16060 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
16070 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
16080 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
16090 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
160a0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
160b0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
160c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
160d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
160e0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
160f0 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
16100 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
16110 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
16120 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
16130 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
16140 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
16150 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16160 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
16170 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
16180 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
16190 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
161a0 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
161b0 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
161c0 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
161d0 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
161e0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
161f0 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
16200 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
16210 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
16220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16230 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16240 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
16250 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16260 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
16270 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
16280 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
16290 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
162a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
162b0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
162c0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  bol defined..** 
162d0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
162e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
162f0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16300 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16310 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16320 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16330 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16340 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16350 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16360 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16370 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16380 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16390 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
163a0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
163b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
163c0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
163d0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
163e0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
163f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16400 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16410 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16420 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16440 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16450 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16460 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16480 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16490 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
164a0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
164b0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
164c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
164d0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
164e0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
164f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16500 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16510 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16520 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16530 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16540 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16550 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16560 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16570 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16580 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16590 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
165a0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
165b0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
165c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
165d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
165e0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
165f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16600 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16610 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
16620 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16630 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16640 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16650 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
16660 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16670 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16680 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16690 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
166a0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
166b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
166c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
166d0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
166e0 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
166f0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
16700 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
16710 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
16720 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
16730 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
16740 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
16750 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16760 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
16770 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
16780 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16790 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
167a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
167b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
167c0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
167d0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
167e0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
167f0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
16800 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
16810 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
16820 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
16830 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
16840 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
16850 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
16860 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
16870 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16880 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16890 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
168a0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
168b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
168c0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
168d0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
168e0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
168f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
16900 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
16910 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
16920 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16930 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
16940 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16950 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16960 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16970 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16980 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16990 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
169a0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
169b0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
169c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
169d0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
169e0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
169f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16a00 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16a10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
16a20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16a30 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16a40 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16a50 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16a60 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16a70 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16a80 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16a90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16aa0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16ab0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16ac0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16ad0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
16ae0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
16af0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
16b00 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
16b10 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
16b20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
16b30 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
16b40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
16b50 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
16b60 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
16b70 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16b80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16b90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16ba0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
16bb0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
16bc0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16bd0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16be0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
16bf0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16c00 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16c10 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16c20 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
16c30 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
16c40 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16c50 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
16c60 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
16c70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
16c80 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16c90 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
16ca0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
16cb0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
16cc0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
16cd0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
16ce0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
16cf0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
16d00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
16d10 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
16d20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
16d30 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
16d40 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
16d50 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
16d60 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
16d70 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
16d80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
16d90 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
16da0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
16db0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
16dc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
16dd0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
16de0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
16df0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
16e00 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
16e10 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
16e20 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16e30 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
16e40 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
16e50 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
16e60 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
16e70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
16e80 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
16e90 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
16ea0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
16eb0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
16ec0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16ed0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
16ee0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16ef0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16f00 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
16f10 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
16f20 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
16f30 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
16f40 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
16f50 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
16f60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
16f70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16f80 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16f90 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
16fa0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16fb0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
16fc0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
16fd0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
16fe0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
16ff0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17000 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17010 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17020 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17030 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17040 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17050 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17060 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17070 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17080 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
17090 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
170a0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
170b0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
170c0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
170d0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
170e0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
170f0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17100 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17110 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17120 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17130 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17140 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17150 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17160 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17170 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17180 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17190 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
171a0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
171b0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
171c0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
171d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
171e0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
171f0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17200 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17210 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17220 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17230 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17240 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17250 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17260 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17270 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17280 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17290 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
172a0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
172b0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
172c0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
172d0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
172e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
172f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17300 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17310 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17320 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17330 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17340 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17350 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17360 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
17370 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17380 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17390 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
173a0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
173b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
173c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
173d0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
173e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
173f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17400 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
17410 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
17420 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
17430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
17440 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
17450 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
17460 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
17470 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
17480 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
17490 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
174a0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
174b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
174c0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
174d0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
174e0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
174f0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
17500 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
17510 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
17520 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
17530 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
17540 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
17550 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
17560 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
17570 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
17580 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
17590 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
175a0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
175b0 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
175c0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
175d0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
175e0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
175f0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
17600 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
17610 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
17620 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
17630 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
17640 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
17650 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
17660 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
17670 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
17680 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
17690 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
176a0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
176b0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
176c0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
176d0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
176e0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
176f0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
17700 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
17710 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
17720 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
17730 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
17740 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
17750 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
17760 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
17770 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
17780 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
17790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
177a0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
177b0 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
177c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
177d0 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
177e0 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
177f0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
17800 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
17810 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
17820 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
17830 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
17840 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17850 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
17860 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
17870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17880 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
17890 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
178a0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
178b0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
178c0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
178d0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
178e0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
178f0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17900 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17910 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17920 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17930 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17940 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17950 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17960 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17970 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17980 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17990 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
179a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
179b0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
179c0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
179d0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
179e0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
179f0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
17a00 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17a10 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17a20 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17a30 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17a40 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17a50 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17a60 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17a70 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17a80 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17a90 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17aa0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17ab0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17ac0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17ad0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
17ae0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17af0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
17b00 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17b10 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17b20 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17b30 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17b40 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17b50 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17b60 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17b70 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17b80 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17b90 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17ba0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17bb0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17bc0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17bd0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17be0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17bf0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17c00 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17c10 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17c20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17c30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17c40 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17c50 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17c60 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17c70 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17c80 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17c90 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17ca0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17cb0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17cc0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17cd0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17ce0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17cf0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17d00 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17d10 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17d20 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17d30 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17d40 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17d50 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17d60 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17d70 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17d90 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17da0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17db0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17dc0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17dd0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17de0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17df0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17e00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17e10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17e20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17e30 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17e40 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17e50 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17e60 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17e70 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17e80 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17e90 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
17ea0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
17eb0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17ec0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
17ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17ee0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
17ef0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
17f00 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
17f10 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17f20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
17f30 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
17f40 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
17f50 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
17f60 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17f70 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17f80 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
17f90 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
17fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17fb0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
17fc0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17fd0 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
17fe0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
17ff0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
18000 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
18010 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
18020 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
18030 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
18040 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
18050 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
18060 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
18070 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
18080 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
18090 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
180a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
180b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
180c0 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
180d0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
180e0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
180f0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
18100 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
18110 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
18120 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
18130 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
18140 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
18150 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
18160 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18170 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
18180 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
18190 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
181a0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
181b0 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
181c0 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
181d0 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
181e0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
181f0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
18200 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
18210 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
18220 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
18230 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
18240 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
18250 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
18260 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
18270 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
18280 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
18290 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
182a0 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
182b0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
182c0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
182d0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
182e0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
182f0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
18300 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
18310 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
18320 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
18330 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
18340 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
18350 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
18360 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
18370 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
18380 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
18390 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
183a0 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
183b0 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
183c0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
183d0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
183e0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
183f0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
18400 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
18410 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
18420 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
18430 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
18440 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
18450 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
18460 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
18470 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
18480 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
18490 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
184a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
184b0 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
184c0 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
184d0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
184e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
184f0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
18500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
18510 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
18520 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
18530 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
18540 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
18550 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18560 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
18570 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
18580 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
18590 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
185a0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
185b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
185c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
185d0 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
185e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
185f0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
18600 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
18610 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
18620 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
18630 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
18640 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
18650 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
18660 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
18670 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
18680 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
18690 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
186a0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
186b0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
186c0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
186d0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
186e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
186f0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
18700 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
18710 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
18720 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
18730 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
18740 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
18750 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
18760 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
18770 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
18780 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
18790 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
187a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
187b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
187c0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
187d0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
187e0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
187f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18800 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18810 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
18820 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18830 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18840 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18850 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18860 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18870 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18880 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
18890 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
188a0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
188b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
188c0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
188d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
188e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
188f0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
18900 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
18910 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
18920 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
18930 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
18940 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
18950 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
18960 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
18970 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
18980 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
18990 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
189a0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
189b0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
189c0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
189d0 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
189e0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
189f0 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
18a00 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
18a10 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
18a20 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
18a30 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
18a40 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
18a50 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
18a60 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
18a70 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
18a80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
18a90 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
18aa0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
18ab0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
18ac0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
18ad0 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
18ae0 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
18af0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
18b00 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
18b10 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
18b20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18b30 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
18b40 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
18b50 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
18b60 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
18b70 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
18b80 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
18b90 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
18ba0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18bb0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
18bc0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
18bd0 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
18be0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
18bf0 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
18c00 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
18c10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
18c20 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
18c30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
18c40 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
18c50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
18c60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
18c70 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
18c80 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18c90 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18ca0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18cb0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18cc0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18cd0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18ce0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18cf0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18d00 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18d10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18d20 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18d30 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18d40 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18d50 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
18d60 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
18d70 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18d80 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18d90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
18da0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
18db0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
18dc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18dd0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
18de0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
18df0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
18e00 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
18e10 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
18e20 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
18e30 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
18e40 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
18e50 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
18e60 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
18e70 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
18e80 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
18e90 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
18ea0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
18eb0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
18ec0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
18ed0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
18ee0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
18ef0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
18f00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
18f10 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
18f20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
18f30 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
18f40 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
18f50 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
18f60 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
18f70 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
18f80 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
18f90 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
18fa0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
18fb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
18fc0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
18fd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
18fe0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
18ff0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
19000 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
19010 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
19020 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
19030 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
19040 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
19050 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
19060 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
19070 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
19080 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
19090 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
190a0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
190b0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
190c0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
190d0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
190e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
190f0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
19100 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
19110 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
19120 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
19130 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
19140 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
19150 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
19160 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
19170 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
19180 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
19190 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
191a0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
191b0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
191c0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
191d0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
191e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
191f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
19200 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
19210 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
19220 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
19230 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
19240 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
19250 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
19260 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
19270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
19280 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
19290 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
192a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
192b0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
192c0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
192d0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
192e0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
192f0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
19300 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
19310 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
19320 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19330 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
19340 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
19350 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
19360 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
19370 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
19380 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
19390 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
193a0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
193b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
193c0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
193d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
193e0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
193f0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
19400 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
19410 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19420 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
19430 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
19440 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
19450 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19460 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
19470 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19480 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
19490 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
194a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
194b0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
194c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
194d0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
194e0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
194f0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
19500 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
19510 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
19520 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
19530 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19540 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
19550 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
19560 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
19570 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
19580 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
19590 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
195a0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
195b0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
195c0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
195d0 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
195e0 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
195f0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19600 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19610 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
19620 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
19630 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
19640 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
19650 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
19660 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19670 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
19680 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
19690 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
196a0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
196b0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
196c0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
196d0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
196e0 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
196f0 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
19700 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19710 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
19720 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
19730 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
19740 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
19750 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
19760 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
19770 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
19780 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
19790 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
197a0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
197b0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
197c0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
197d0 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
197e0 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
197f0 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
19800 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19810 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
19820 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
19830 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
19840 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
19850 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
19860 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
19870 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19880 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
19890 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
198a0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
198b0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
198c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
198d0 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
198e0 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
198f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
19900 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19910 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
19920 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
19930 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
19940 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
19950 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
19960 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
19970 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
19980 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
19990 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
199a0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
199b0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
199c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
199d0 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
199e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
199f0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
19a00 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19a10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19a20 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
19a30 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
19a40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
19a50 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
19a60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19a70 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19a80 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19a90 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19aa0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19ab0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19ac0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19ad0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19ae0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19af0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19b00 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19b10 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19b20 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19b30 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19b40 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19b50 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19b60 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19b70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19b80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19b90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
19ba0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
19bb0 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
19bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19bd0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
19be0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
19bf0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
19c00 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
19c10 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19c20 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
19c30 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
19c40 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
19c50 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
19c60 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
19c70 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19c80 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19c90 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
19ca0 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
19cb0 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
19cc0 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
19cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19ce0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19cf0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
19d00 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
19d10 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19d20 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
19d30 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
19d40 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
19d50 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
19d60 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
19d70 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
19d80 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
19d90 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
19da0 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
19db0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
19dc0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
19dd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
19de0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
19df0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
19e00 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
19e10 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
19e20 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19e30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
19e40 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
19e50 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
19e60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
19e70 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
19e80 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
19e90 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
19ea0 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
19eb0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
19ec0 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
19ed0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
19ee0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
19ef0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
19f00 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
19f10 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
19f20 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19f30 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
19f40 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
19f50 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
19f60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19f70 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
19f80 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19f90 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
19fa0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
19fb0 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
19fc0 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
19fd0 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
19fe0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
19ff0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1a000 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1a010 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1a020 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1a030 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1a040 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1a050 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1a060 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1a070 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1a080 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1a090 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1a0a0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1a0b0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1a0c0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1a0d0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
1a0e0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
1a0f0 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
1a100 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1a110 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a120 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1a130 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1a140 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1a150 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1a160 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1a170 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1a180 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1a190 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1a1a0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1a1b0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1a1c0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1a1d0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1a1e0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1a1f0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1a200 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1a210 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1a220 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1a230 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1a240 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1a250 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1a260 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1a270 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a280 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1a290 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1a2a0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1a2b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1a2c0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1a2d0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1a2e0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1a2f0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1a300 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1a310 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a320 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1a330 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1a340 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1a350 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1a360 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1a370 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1a380 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1a390 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1a3a0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1a3b0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1a3c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
1a3d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
1a3e0 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
1a3f0 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
1a400 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
1a410 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
1a420 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
1a430 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
1a440 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
1a450 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
1a460 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
1a470 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
1a480 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
1a490 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
1a4a0 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
1a4b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1a4c0 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
1a4d0 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
1a4e0 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
1a4f0 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
1a500 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
1a510 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
1a520 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1a530 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
1a540 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
1a550 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
1a560 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
1a570 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
1a580 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
1a590 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
1a5a0 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
1a5b0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
1a5c0 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
1a5d0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
1a5e0 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
1a5f0 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
1a600 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
1a610 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
1a620 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
1a630 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
1a640 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
1a650 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
1a660 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
1a670 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
1a680 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
1a690 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
1a6a0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
1a6b0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
1a6c0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
1a6d0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
1a6e0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
1a6f0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
1a700 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
1a710 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
1a720 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
1a730 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1a740 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1a750 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1a760 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1a770 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a780 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1a790 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1a7a0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1a7b0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1a7c0 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1a7d0 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1a7e0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1a7f0 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
1a800 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
1a810 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a820 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1a830 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1a840 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1a850 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1a860 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1a870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1a880 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1a890 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
1a8a0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1a8b0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1a8c0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1a8d0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1a8e0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1a8f0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1a900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1a910 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1a920 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1a930 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1a940 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ndler..*/.SQLITE
1a950 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a960 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1a970 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
1a980 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
1a990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a9a0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1a9b0 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
1a9c0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1a9d0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1a9e0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1a9f0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1aa00 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1aa10 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1aa20 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1aa30 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1aa40 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1aa50 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1aa60 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1aa70 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1aa80 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1aa90 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1aaa0 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1aab0 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1aac0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1aad0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1aae0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1aaf0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1ab00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ab10 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1ab20 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
1ab30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1ab40 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
1ab50 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1ab60 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1ab70 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1ab80 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1ab90 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1aba0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1abb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1abc0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1abd0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1abe0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1abf0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1ac00 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
1ac10 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1ac20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1ac30 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1ac40 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1ac50 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1ac60 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1ac70 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1ac80 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1ac90 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1aca0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1acb0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1acc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1acd0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1ace0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1acf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1ad00 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1ad10 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1ad20 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
1ad30 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1ad40 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1ad50 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1ad60 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1ad70 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1ad80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1ad90 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1ada0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1adb0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1adc0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1add0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1ade0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1adf0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1ae00 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1ae10 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1ae20 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1ae30 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1ae40 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1ae50 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1ae60 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1ae70 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1ae80 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1ae90 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1aea0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1aeb0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1aec0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1aed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1aee0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1aef0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1af00 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1af10 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1af20 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1af30 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1af40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1af50 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1af60 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1af70 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1af80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1af90 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1afa0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1afb0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1afc0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1afd0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1afe0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1aff0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1b000 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1b010 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1b020 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1b030 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1b040 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1b050 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1b060 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1b070 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1b080 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1b090 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1b0a0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1b0b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1b0c0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1b0d0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1b0e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1b0f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1b100 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1b110 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1b120 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1b130 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1b140 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1b150 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1b160 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1b170 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1b180 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1b190 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1b1a0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1b1b0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1b1c0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1b1d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1b1e0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1b1f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1b200 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1b210 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1b220 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1b230 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b240 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b250 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1b260 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1b270 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b280 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1b290 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1b2a0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1b2b0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1b2c0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1b2d0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1b2e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b2f0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1b300 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1b310 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1b320 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1b330 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1b340 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1b350 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1b360 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1b370 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1b380 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1b390 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1b3a0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1b3b0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1b3c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b3d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b3e0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1b3f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b400 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1b410 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b420 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1b430 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1b440 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b450 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1b460 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b470 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1b480 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b490 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1b4a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b4b0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1b4c0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1b4d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1b4e0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1b4f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1b500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b510 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1b520 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1b530 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1b540 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1b550 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1b560 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1b570 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1b580 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1b590 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1b5a0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1b5b0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1b5c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1b5d0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1b5e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1b5f0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1b600 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1b610 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1b620 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1b630 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1b640 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1b650 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1b660 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1b670 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1b680 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1b690 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1b6a0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1b6b0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1b6c0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1b6d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b6e0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1b6f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b700 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1b710 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1b720 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1b730 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b740 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1b750 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1b760 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1b770 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1b780 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1b790 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1b7a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1b7b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1b7c0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1b7d0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1b7e0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1b7f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1b800 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1b810 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1b820 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1b830 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1b840 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1b850 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1b860 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1b870 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1b880 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1b890 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1b8a0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1b8b0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1b8c0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1b8d0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1b8e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1b8f0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1b900 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1b910 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1b920 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1b930 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b940 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1b950 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
1b960 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1b970 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b980 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1b990 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1b9a0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b9b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b9c0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b9d0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b9e0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b9f0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1ba00 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1ba10 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1ba20 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1ba30 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ba40 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1ba50 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1ba60 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1ba70 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1ba80 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1ba90 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1baa0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1bab0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1bac0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1bad0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1bae0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1baf0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1bb00 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1bb10 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1bb20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1bb30 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1bb40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1bb50 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1bb60 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1bb70 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1bb80 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1bb90 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1bba0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
1bbb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1bbc0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1bbd0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1bbe0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1bbf0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1bc00 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1bc10 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1bc20 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1bc30 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1bc40 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1bc50 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1bc60 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1bc70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1bc80 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1bc90 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1bca0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1bcb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1bcc0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1bcd0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1bce0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1bcf0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1bd00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1bd10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bd20 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1bd30 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1bd40 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1bd50 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1bd60 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1bd70 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1bd80 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1bd90 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1bda0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bdb0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1bdc0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1bdd0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1bde0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1bdf0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1be00 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1be10 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1be20 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1be30 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1be40 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1be50 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1be60 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1be70 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1be80 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1be90 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1bea0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1beb0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1bec0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1bed0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1bee0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1bef0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1bf00 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1bf10 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1bf20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1bf30 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1bf40 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1bf50 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1bf60 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1bf70 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1bf80 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1bf90 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1bfa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1bfb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bfc0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1bfd0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1bfe0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1bff0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1c000 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1c010 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1c020 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c030 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1c040 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1c050 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1c060 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1c070 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c080 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1c090 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1c0a0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1c0b0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1c0c0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1c0d0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1c0e0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1c0f0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1c100 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1c110 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1c120 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1c130 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1c140 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1c150 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1c160 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1c170 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1c180 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c190 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1c1a0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1c1b0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1c1c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1c1d0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1c1e0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1c1f0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1c200 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1c210 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1c220 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1c230 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1c240 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1c250 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
1c260 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1c270 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1c280 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1c290 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1c2a0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
1c2b0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1c2c0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1c2d0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1c2e0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1c2f0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1c300 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1c310 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1c320 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1c330 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1c340 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1c350 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1c360 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1c370 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1c380 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1c390 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1c3a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1c3b0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1c3c0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1c3d0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1c3e0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1c3f0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c400 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c410 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1c420 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c430 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1c440 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c450 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1c460 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1c470 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1c480 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c490 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c4a0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c4b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c4c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c4d0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1c4e0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c4f0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c500 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c510 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c520 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c530 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c540 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1c550 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1c560 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1c570 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1c580 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1c590 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1c5a0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1c5b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c5c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c5d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1c5e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1c5f0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1c600 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1c610 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c620 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1c630 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1c640 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1c650 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1c660 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1c670 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1c680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c690 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1c6a0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c6b0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1c6c0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1c6d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c6e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1c6f0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1c700 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1c710 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1c720 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1c730 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1c740 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1c750 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1c760 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1c770 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1c780 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1c790 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c7a0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1c7b0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1c7c0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1c7d0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1c7e0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1c7f0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1c800 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c810 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1c820 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1c830 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1c840 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1c850 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1c860 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1c870 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1c880 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1c890 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1c8a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c8b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c8c0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c8d0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c8e0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1c8f0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c900 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c910 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c920 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c930 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c940 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c950 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1c960 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1c970 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1c980 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1c990 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1c9a0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1c9b0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1c9c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1c9d0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1c9e0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c9f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1ca00 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1ca10 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1ca20 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1ca30 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1ca40 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1ca50 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1ca60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1ca70 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1ca80 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1ca90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1caa0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1cab0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1cac0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1cad0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1cae0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1caf0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1cb00 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1cb10 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1cb20 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1cb30 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1cb40 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1cb50 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cb60 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1cb70 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1cb80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cb90 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cba0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1cbb0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cbc0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cbd0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cbe0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cbf0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cc00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cc10 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cc20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cc30 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cc40 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1cc50 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1cc60 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1cc70 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1cc80 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1cc90 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1cca0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1ccb0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ccc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ccd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1cce0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ccf0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1cd00 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1cd10 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1cd20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1cd30 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1cd40 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1cd50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cd60 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1cd70 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cd80 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1cd90 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cda0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cdb0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cdc0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cdd0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cde0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cdf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1ce00 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1ce10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1ce20 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1ce30 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1ce40 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1ce50 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ce60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ce70 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ce80 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1ce90 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1cea0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1ceb0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1cec0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1ced0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1cee0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1cef0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1cf00 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1cf10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1cf20 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1cf30 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1cf40 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1cf50 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1cf60 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1cf70 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1cf80 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1cf90 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1cfa0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1cfb0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1cfc0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1cfd0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1cfe0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1cff0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1d000 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d010 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1d020 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1d030 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1d040 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1d050 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1d060 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1d070 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1d080 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1d090 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1d0a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1d0c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1d0d0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1d0e0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1d0f0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1d100 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1d110 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1d120 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1d130 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1d140 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1d150 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1d160 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1d170 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1d180 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1d190 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d1a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1d1b0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1d1c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1d1d0 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1d1e0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1d1f0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1d200 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1d210 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1d220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d230 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1d240 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1d250 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1d260 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d270 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1d280 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1d290 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1d2a0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1d2b0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d2c0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1d2d0 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1d2e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d2f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d300 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1d310 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1d320 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1d330 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1d340 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1d350 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1d360 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1d370 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1d380 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1d390 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1d3a0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d3b0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1d3c0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1d3d0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1d3e0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1d3f0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1d400 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1d410 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1d420 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d430 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1d440 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1d450 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1d460 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1d470 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1d480 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1d490 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1d4a0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1d4b0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1d4c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1d4d0 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1d4e0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1d4f0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1d500 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1d510 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1d520 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1d530 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1d540 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1d550 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1d560 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1d570 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1d580 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1d590 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1d5a0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1d5b0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1d5c0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1d5d0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1d5e0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1d5f0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1d600 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1d610 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1d620 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1d630 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1d640 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1d650 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1d660 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1d670 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1d680 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1d690 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
1d6a0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1d6b0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
1d6c0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
1d6d0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1d6e0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
1d6f0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
1d700 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
1d710 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1d720 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
1d730 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
1d740 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
1d750 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
1d760 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
1d770 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
1d780 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
1d790 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1d7a0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
1d7b0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
1d7c0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1d7d0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1d7e0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1d7f0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1d800 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1d810 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1d820 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1d830 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1d840 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d850 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1d860 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1d870 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1d880 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1d890 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1d8a0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1d8b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1d8c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1d8d0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1d8e0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1d8f0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1d900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1d910 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1d920 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1d930 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1d940 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1d950 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1d960 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1d970 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1d980 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d990 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1d9a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1d9b0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1d9c0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1d9d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1d9e0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1d9f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1da00 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1da10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1da30 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1da40 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1da50 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1da60 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1da70 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1da80 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1da90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1daa0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1dab0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1dac0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1dad0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1dae0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1daf0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1db00 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1db10 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1db20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1db30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1db40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1db50 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1db60 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1db70 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1db80 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1db90 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1dba0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1dbb0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1dbc0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1dbd0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1dbe0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1dbf0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1dc00 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1dc10 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1dc20 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1dc30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1dc40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1dc50 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1dc60 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dc70 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1dc80 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1dc90 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1dca0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1dcb0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1dcc0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1dcd0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1dce0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1dcf0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1dd00 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1dd10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1dd20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1dd30 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1dd40 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1dd50 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1dd60 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1dd70 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1dd80 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dd90 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1dda0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1ddb0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1ddc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ddd0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1dde0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1ddf0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1de00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1de10 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1de20 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1de30 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1de40 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
1de50 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1de60 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1de70 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
1de80 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1de90 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1dea0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1deb0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1dec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ded0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1dee0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1def0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1df00 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1df10 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1df20 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1df30 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1df40 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1df50 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1df60 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1df70 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1df80 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1df90 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1dfa0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1dfb0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1dfc0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1dfd0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1dfe0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1dff0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1e000 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1e010 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1e020 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1e030 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1e040 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1e050 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1e060 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1e070 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1e080 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1e090 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1e0a0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1e0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1e0c0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1e0d0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1e0e0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1e0f0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1e100 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1e110 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1e120 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1e130 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1e140 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e150 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1e160 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1e170 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1e180 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1e190 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1e1a0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1e1b0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1e1c0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1e1d0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1e1e0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1e1f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1e200 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1e210 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1e220 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1e230 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1e240 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1e250 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1e260 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1e270 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1e280 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1e290 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1e2a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e2b0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1e2c0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e2d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1e2e0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1e2f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1e300 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1e310 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e320 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1e330 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1e340 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1e350 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1e360 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1e370 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1e380 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1e390 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e3a0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1e3b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e3c0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1e3d0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1e3e0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1e3f0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1e400 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1e410 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1e420 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1e430 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1e440 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e450 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1e460 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1e470 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1e480 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1e490 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1e4a0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1e4b0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1e4c0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1e4d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1e4e0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1e4f0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1e500 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1e510 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1e520 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1e530 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1e540 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1e550 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1e560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1e570 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1e580 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1e590 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1e5a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1e5b0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1e5c0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1e5d0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1e5e0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1e5f0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1e600 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1e610 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e620 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1e630 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1e640 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1e650 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1e660 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1e670 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1e680 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e690 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1e6a0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1e6b0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1e6c0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1e6d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1e6e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1e6f0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1e700 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e710 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1e720 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1e730 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1e740 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1e750 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1e760 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1e770 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1e780 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1e790 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1e7a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e7b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e7c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1e7d0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1e7e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1e7f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1e800 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1e810 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1e820 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1e830 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1e840 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1e850 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1e860 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1e870 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1e880 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1e890 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1e8a0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1e8b0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1e8c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1e8d0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1e8e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1e8f0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1e900 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1e910 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1e920 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1e930 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1e940 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1e950 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1e960 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1e970 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e980 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1e990 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1e9a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e9b0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1e9c0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1e9d0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1e9e0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1e9f0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1ea00 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1ea10 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1ea20 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1ea30 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1ea40 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1ea50 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1ea60 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1ea70 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1ea80 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1ea90 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1eaa0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1eab0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1eac0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1ead0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1eae0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1eaf0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1eb00 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1eb10 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1eb20 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1eb30 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1eb40 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1eb50 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1eb60 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1eb70 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1eb80 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1eb90 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1eba0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1ebb0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1ebc0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1ebd0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1ebe0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1ebf0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1ec00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ec10 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1ec20 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1ec30 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1ec40 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1ec50 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1ec60 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1ec70 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1ec80 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1ec90 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1eca0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1ecb0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1ecc0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1ecd0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1ece0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1ecf0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1ed00 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1ed10 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1ed20 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1ed30 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1ed40 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1ed50 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1ed60 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1ed70 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1ed80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1ed90 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1eda0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1edb0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1edc0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1edd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1ede0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1edf0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1ee00 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1ee10 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ee20 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1ee30 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1ee40 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1ee50 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1ee60 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1ee70 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1ee80 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1ee90 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1eea0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1eeb0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1eec0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1eed0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1eee0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1eef0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1ef00 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1ef10 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1ef20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1ef30 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1ef40 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1ef50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ef60 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1ef70 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1ef80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ef90 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1efa0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1efb0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1efc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1efd0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1efe0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1eff0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f000 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1f010 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1f020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f030 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1f040 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1f050 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1f060 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1f070 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1f080 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1f090 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1f0a0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1f0b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f0c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1f0d0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1f0e0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1f0f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1f100 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1f110 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1f120 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1f130 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1f140 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f150 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1f160 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1f170 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1f180 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1f190 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1f1a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f1b0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1f1c0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1f1d0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1f1e0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1f1f0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1f200 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1f210 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1f220 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1f230 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1f240 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1f250 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1f260 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f270 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1f280 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1f290 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f2a0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1f2b0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1f2c0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1f2d0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1f2e0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1f2f0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1f300 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1f310 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1f320 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1f330 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1f340 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1f350 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f360 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1f370 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1f380 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1f390 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1f3a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1f3b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1f3c0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1f3d0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1f3e0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1f3f0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f400 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f410 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1f420 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1f430 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f440 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1f450 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f460 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f470 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1f480 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f490 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1f4a0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1f4b0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1f4c0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1f4d0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1f4e0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1f4f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1f500 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1f510 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1f520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1f530 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1f540 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1f550 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1f560 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1f570 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1f580 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1f590 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1f5a0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1f5b0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1f5c0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1f5d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1f5e0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1f5f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1f600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1f610 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1f620 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1f630 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1f640 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1f650 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1f660 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1f670 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1f680 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1f690 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1f6a0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1f6b0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1f6c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1f6d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1f6e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1f6f0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1f700 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1f710 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1f720 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1f730 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1f740 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1f750 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1f760 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1f770 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1f780 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1f790 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1f7a0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1f7b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1f7c0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1f7d0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1f7e0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1f7f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1f800 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1f810 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1f820 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1f830 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1f840 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1f850 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1f860 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1f870 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1f880 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1f890 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1f8a0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1f8b0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1f8c0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1f8d0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1f8e0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1f8f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1f900 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1f910 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1f920 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1f930 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1f940 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1f950 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1f960 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1f970 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1f980 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1f990 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1f9a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f9b0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1f9c0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1f9d0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1f9e0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1f9f0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1fa00 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1fa10 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1fa20 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1fa30 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1fa40 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1fa50 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1fa60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa80 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1fa90 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1faa0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1fab0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fac0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1fad0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1fae0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1faf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fb00 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fb10 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1fb20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1fb30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fb40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1fb60 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1fb70 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1fb80 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1fb90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fba0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1fbb0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1fbc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fbd0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fbe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fbf0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1fc00 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1fc10 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1fc20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1fc30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fc40 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1fc50 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1fc60 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1fc70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fc80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fc90 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1fca0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1fcb0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1fcc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fcd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fce0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1fcf0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1fd00 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1fd10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fd20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd30 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1fd40 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1fd50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1fd60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fd70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fd80 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1fd90 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1fda0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1fdb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1fdc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fdd0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1fde0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1fdf0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fe00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fe10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fe20 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1fe30 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1fe40 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1fe50 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fe60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fe70 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1fe80 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1fe90 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fea0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1feb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fec0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1fed0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1fee0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1fef0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ff00 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ff10 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1ff20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1ff30 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1ff40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ff50 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ff60 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1ff70 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1ff80 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ff90 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ffa0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1ffb0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1ffc0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ffd0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ffe0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fff0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
20000 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
20010 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20020 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20030 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20040 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
20050 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
20060 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
20070 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
20080 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
20090 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
200a0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
200b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
200c0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
200d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200e0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
200f0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
20100 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
20110 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20120 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20130 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
20140 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
20150 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
20160 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20170 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20180 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
20190 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
201a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201b0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
201c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201d0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
201e0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
201f0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
20200 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20210 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20220 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
20230 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
20240 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
20250 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20260 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20270 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
20280 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
20290 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
202a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
202b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
202c0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
202d0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
202e0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
202f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
20310 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
20320 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
20330 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20340 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20360 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
20370 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
20380 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
20390 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
203a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
203b0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
203c0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
203d0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
203e0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
203f0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
20400 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
20410 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
20420 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
20430 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
20440 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
20450 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
20460 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
20470 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
20480 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
20490 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
204a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
204b0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
204c0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
204d0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
204e0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
204f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
20500 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
20510 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
20520 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
20530 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
20540 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
20550 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
20560 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
20570 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
20580 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
20590 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
205a0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
205b0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
205c0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
205d0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
205e0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
205f0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
20600 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
20610 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
20620 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
20630 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
20640 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
20650 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
20660 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
20670 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
20680 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
20690 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
206a0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
206b0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
206c0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
206d0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
206e0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
206f0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
20700 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
20710 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
20720 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
20730 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
20740 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
20750 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
20760 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
20770 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
20780 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
20790 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
207a0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
207b0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
207c0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
207d0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
207e0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
207f0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
20800 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
20810 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
20820 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
20830 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
20840 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
20850 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
20860 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
20870 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
20880 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
20890 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
208a0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
208b0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
208c0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
208d0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
208e0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
208f0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
20900 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
20910 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
20920 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20930 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
20940 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
20950 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
20960 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
20970 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
20980 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
20990 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
209a0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
209b0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
209c0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
209d0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
209e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
209f0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
20a00 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
20a10 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
20a20 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
20a30 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
20a40 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
20a50 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
20a60 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
20a70 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
20a80 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
20a90 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
20aa0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
20ab0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
20ac0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
20ad0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
20ae0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
20af0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
20b00 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
20b10 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
20b20 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
20b30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
20b40 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
20b50 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
20b60 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
20b70 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
20b80 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
20b90 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
20ba0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
20bb0 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
20bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20bd0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
20be0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
20bf0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
20c00 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
20c10 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
20c20 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
20c30 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
20c40 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
20c50 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
20c60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
20c70 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
20c80 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
20c90 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
20ca0 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
20cb0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20cc0 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
20cd0 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
20ce0 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
20cf0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
20d00 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
20d10 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  ck X..**.** ^Onl
20d20 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
20d30 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
20d40 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
20d50 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
20d60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20d70 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
20d80 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
20d90 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
20da0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
20db0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
20dc0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
20dd0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
20de0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
20df0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20e00 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
20e10 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
20e20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
20e30 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
20e40 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
20e50 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
20e60 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
20e70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
20e80 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
20e90 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
20ea0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
20eb0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
20ec0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
20ed0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
20ee0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
20ef0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20f00 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
20f10 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
20f20 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
20f30 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
20f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
20f50 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
20f60 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
20f70 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
20f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20f90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20fa0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
20fb0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
20fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20fd0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
20fe0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
20ff0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21000 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
21010 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
21020 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
21030 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
21040 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
21050 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
21060 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
21070 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
21080 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
21090 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
210a0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
210b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
210c0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
210d0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
210e0 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
210f0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
21100 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21110 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
21120 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
21130 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21140 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
21150 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21160 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
21170 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
21180 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
21190 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
211a0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
211b0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
211c0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
211d0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
211e0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
211f0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
21200 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
21210 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
21220 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21230 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
21240 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
21250 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
21260 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
21270 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
21280 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
21290 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
212a0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
212b0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
212c0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
212d0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
212e0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
212f0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
21300 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
21310 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
21320 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
21330 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
21340 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
21350 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
21360 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
21370 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
21380 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
21390 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
213a0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
213b0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
213c0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
213d0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
213e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
213f0 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
21400 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
21410 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
21420 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21430 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21440 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
21450 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
21460 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
21470 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
21480 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
21490 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
214a0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
214b0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
214c0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
214d0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
214e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
214f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21500 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
21510 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
21520 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
21530 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
21540 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
21550 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
21560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21570 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
21580 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
21590 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
215a0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
215b0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
215c0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
215d0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
215e0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
215f0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
21600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
21610 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
21620 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
21630 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21640 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
21650 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
21660 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
21670 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
21680 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
21690 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
216a0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
216b0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
216c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
216d0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
216e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
216f0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
21700 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
21710 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
21720 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
21730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
21740 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
21750 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21760 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
21770 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
21780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
21790 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
217a0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
217b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
217c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
217d0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
217e0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
217f0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21800 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21810 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
21820 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
21830 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
21840 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
21850 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
21860 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
21870 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
21880 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
21890 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
218a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
218b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
218c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
218d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
218e0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
218f0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
21900 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21910 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21920 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21930 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21940 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
21950 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
21960 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
21970 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
21980 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
21990 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
219a0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
219b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
219c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
219d0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
219e0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
219f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
21a00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21a10 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
21a20 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
21a30 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
21a40 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
21a50 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
21a60 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21a70 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
21a80 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
21a90 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
21aa0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
21ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
21ac0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
21ad0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
21ae0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
21af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21b00 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
21b10 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
21b20 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
21b30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
21b40 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
21b50 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
21b60 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
21b70 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
21b80 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
21b90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21ba0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
21bb0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
21bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21bd0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
21be0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
21bf0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
21c00 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
21c10 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
21c20 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
21c30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21c40 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
21c50 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
21c60 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
21c70 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
21c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21c90 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
21ca0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
21cb0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
21cc0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
21cd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
21ce0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
21cf0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
21d00 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
21d10 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
21d20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
21d30 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21d40 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
21d50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21d60 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
21d70 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
21d80 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
21d90 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
21da0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
21db0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
21dc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21dd0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
21de0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
21df0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
21e00 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
21e10 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
21e20 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21e30 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
21e40 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
21e50 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
21e60 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
21e70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
21e80 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
21e90 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
21ea0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
21eb0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21ec0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21ed0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
21ee0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
21ef0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21f00 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
21f10 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
21f20 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
21f30 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
21f40 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
21f50 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
21f60 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
21f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
21f80 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
21f90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21fa0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
21fb0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
21fc0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
21fd0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
21fe0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
21ff0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
22000 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
22010 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
22020 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
22030 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
22040 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
22050 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
22060 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
22070 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
22080 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
22090 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
220a0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
220b0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
220c0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
220d0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
220e0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
220f0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
22100 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
22110 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
22120 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
22130 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
22140 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
22150 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
22160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
22170 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
22180 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
22190 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
221a0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
221b0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
221c0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
221d0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
221e0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
221f0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
22200 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
22210 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
22220 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
22230 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
22240 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
22250 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
22260 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
22270 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
22280 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
22290 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
222a0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
222b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
222c0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
222d0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
222e0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
222f0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
22300 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
22310 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
22320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
22330 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
22340 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
22350 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
22360 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
22370 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
22380 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
22390 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
223a0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
223b0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
223c0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
223d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
223e0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
223f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
22400 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
22410 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
22420 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
22430 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
22440 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
22450 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
22460 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
22470 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
22480 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
22490 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
224a0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
224b0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
224c0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
224d0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
224e0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
224f0 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
22500 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
22510 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
22520 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
22530 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
22540 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
22550 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
22560 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
22570 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
22580 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
22590 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
225a0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
225b0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
225c0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
225d0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
225e0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
225f0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
22600 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
22610 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
22620 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
22630 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
22640 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
22650 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
22660 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
22670 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
22680 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
22690 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
226a0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
226b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
226c0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
226d0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
226e0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
226f0 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
22700 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
22710 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
22720 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
22730 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
22740 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
22750 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
22760 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
22770 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
22780 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
22790 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
227a0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
227b0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
227c0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
227d0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
227e0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
227f0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
22800 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
22810 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
22820 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
22830 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
22840 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
22850 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
22860 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
22870 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
22880 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
22890 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
228a0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
228b0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
228c0 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
228d0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
228e0 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
228f0 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
22900 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
22910 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
22920 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
22930 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
22940 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
22950 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
22960 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
22970 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
22980 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
22990 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
229a0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
229b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
229c0 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
229d0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
229e0 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
229f0 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
22a00 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
22a10 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
22a20 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
22a30 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
22a40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22a50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22a60 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22a70 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
22a80 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
22a90 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22aa0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
22ab0 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20  o", "rw" or.**  
22ac0 20 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70     "rwc". Attemp
22ad0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
22ae0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
22af0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e  e is an error)^.
22b00 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
22b10 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
22b20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22b30 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
22b40 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
22b50 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
22b60 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
22b70 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
22b80 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
22b90 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
22ba0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
22bb0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  to sqlite3_prepa
22bc0 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  re_v2(). ^If the
22bd0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
22be0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
22bf0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
22c00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22c10 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
22c20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
22c30 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
22c40 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
22c50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
22c60 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
22c70 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
22c80 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
22c90 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
22ca0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
22cb0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
22cc0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
22cd0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
22ce0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
22cf0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
22d00 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20  n_v2() is .**   
22d10 20 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e    used, it is an
22d20 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
22d30 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68  y a value for th
22d40 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
22d50 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20   that is .**    
22d60 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
22d70 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
22d80 69 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61  ified by the fla
22d90 67 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  gs passed as the
22da0 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70   third .**     p
22db0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
22dc0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
22dd0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
22de0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22df0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22e00 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
22e10 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
22e20 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
22e30 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
22e40 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
22e50 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
22e60 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22e70 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
22e80 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
22e90 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
22ea0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
22eb0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
22ec0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
22ed0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
22ee0 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
22ef0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
22f00 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22f10 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
22f20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
22f30 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22f40 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
22f50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
22f60 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
22f70 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
22f80 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
22f90 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
22fa0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
22fb0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
22fc0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22fd0 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
22fe0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22ff0 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
23000 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
23010 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
23020 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
23030 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
23040 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
23050 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
23060 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23070 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
23080 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
23090 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
230a0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
230b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
230c0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
230d0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
230e0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
230f0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
23100 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
23110 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
23120 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
23130 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
23140 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
23150 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
23160 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
23170 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
23180 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
23190 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
231a0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
231b0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
231c0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
231d0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
231e0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
231f0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
23200 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
23210 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
23220 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23230 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
23240 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
23250 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
23260 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
23270 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
23280 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23290 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
232a0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
232b0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
232c0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
232d0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
232e0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
232f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
23300 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
23310 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
23320 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
23330 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
23340 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
23350 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
23360 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
23370 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
23380 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
23390 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
233a0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
233b0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
233c0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
233d0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
233e0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
233f0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
23400 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
23410 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
23420 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
23430 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
23440 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
23450 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
23460 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
23470 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
23480 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
23490 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
234a0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
234b0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
234c0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
234d0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
234e0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
234f0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
23500 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
23510 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
23520 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
23530 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
23540 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
23550 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
23560 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
23570 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
23580 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
23590 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
235a0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
235b0 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
235c0 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
235d0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
235e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
235f0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
23600 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
23610 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
23620 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23630 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
23640 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
23650 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
23660 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
23670 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
23680 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
23690 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
236a0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
236b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
236c0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
236d0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
236e0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
236f0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
23700 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
23710 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23720 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
23730 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
23740 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
23750 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
23760 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
23770 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
23780 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
23790 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
237a0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
237b0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
237c0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
237d0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
237e0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
237f0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
23800 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
23810 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23820 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
23830 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
23840 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
23850 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
23860 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
23870 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
23880 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
23890 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
238a0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
238b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
238c0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
238d0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
238e0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
238f0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
23900 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23910 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
23920 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23930 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
23940 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
23950 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
23960 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
23970 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
23980 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
23990 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
239a0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
239b0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
239c0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
239d0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
239e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
239f0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
23a00 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51  open_v2()..*/.SQ
23a10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
23a20 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
23a30 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
23a40 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
23a50 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
23a60 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
23a70 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
23a80 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
23a90 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
23aa0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
23ab0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
23ac0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
23ad0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23ae0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23af0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
23b00 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23b10 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23b20 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23b30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
23b40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23b50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
23b60 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
23b70 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23b80 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
23b90 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
23ba0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
23bb0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
23bc0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
23bd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
23be0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
23bf0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
23c00 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
23c10 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
23c20 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23c30 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
23c40 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
23c50 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eters.**.** This
23c60 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f   is a utility ro
23c70 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f  utine, useful to
23c80 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23c90 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
23ca0 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  s.** to see if a
23cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
23cc0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
23cd0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
23ce0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
23cf0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
23d00 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
23d10 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  lue of the query
23d20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23d30 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  * The zFilename 
23d40 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
23d50 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
23d60 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
23d70 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68   xOpen().** meth
23d80 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c  od of a VFS impl
23d90 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
23da0 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74   zParam argument
23db0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23dc0 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72  the.** query par
23dd0 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20  ameter we seek. 
23de0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
23df0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
23e00 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a  of the zParam.**
23e10 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
23e20 20 65 78 69 73 74 73 2e 20 20 49 66 20 74 68 65   exists.  If the
23e30 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20   parameter does 
23e40 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69 73 20  not exist, this 
23e50 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72  routine.** retur
23e60 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
23e70 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
23e80 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65  zFilename argume
23e90 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  nt to this funct
23ea0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  ion is not a poi
23eb0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
23ec0 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20  .** passed into 
23ed0 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65  the xOpen VFS me
23ee0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
23ef0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
23f00 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e  routine.** is un
23f10 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
23f20 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
23f30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
23f40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23f50 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23f60 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
23f70 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
23f80 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a  har *zParam);...
23f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23fa0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
23fb0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
23fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
23fd0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
23fe0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
23ff0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
24000 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
24010 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
24020 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
24030 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
24040 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
24050 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24060 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
24070 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
24080 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
24090 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
240a0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
240b0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
240c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
240d0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
240e0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
240f0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
24100 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
24110 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
24120 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
24130 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
24140 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
24150 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
24160 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
24170 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
24180 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
24190 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
241a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
241b0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
241c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
241d0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
241e0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
241f0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
24200 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
24210 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
24220 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
24230 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
24240 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24250 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24260 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24270 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
24280 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
24290 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
242a0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
242b0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
242c0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
242d0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
242e0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
242f0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
24300 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
24310 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
24320 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
24330 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
24340 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
24350 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
24360 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
24370 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
24380 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
24390 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
243a0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
243b0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
243c0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
243d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
243e0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
243f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
24400 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
24410 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
24420 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
24430 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
24440 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
24450 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
24460 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
24470 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
24480 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
24490 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
244a0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
244b0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
244c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
244d0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
244e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
244f0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
24500 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
24510 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
24520 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
24530 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
24540 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
24550 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
24560 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
24570 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
24580 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
24590 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
245a0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
245b0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
245c0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
245d0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
245e0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
245f0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
24600 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
24610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
24620 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
24630 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
24640 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
24650 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
24660 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
24670 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
24680 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
24690 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
246a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
246b0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
246c0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
246d0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
246e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
246f0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
24700 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
24710 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
24720 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
24730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24740 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
24750 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24760 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24770 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
24780 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
24790 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
247a0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
247b0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
247c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
247d0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
247e0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
247f0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
24800 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
24810 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
24820 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
24830 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
24840 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
24850 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
24860 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
24870 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
24880 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
24890 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
248a0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
248b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
248c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
248d0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
248e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
248f0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
24900 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
24910 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
24920 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
24930 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
24940 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
24950 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
24960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24970 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24980 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
24990 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
249a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
249b0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
249c0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
249d0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
249e0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
249f0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
24a00 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
24a10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
24a20 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
24a30 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
24a40 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
24a50 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
24a60 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
24a70 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
24a80 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
24a90 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
24aa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
24ab0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
24ac0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
24ad0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
24ae0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
24af0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
24b00 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
24b10 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
24b20 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
24b30 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
24b40 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
24b50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24b60 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
24b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24b80 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
24b90 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
24ba0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
24bb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
24bc0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
24bd0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
24be0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
24bf0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
24c00 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
24c10 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
24c20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
24c30 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
24c40 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
24c50 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
24c60 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
24c70 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
24c80 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
24c90 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
24ca0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
24cb0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
24cc0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
24cd0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
24ce0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
24cf0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
24d00 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
24d10 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
24d20 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
24d30 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
24d40 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
24d50 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
24d60 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
24d70 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
24d80 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
24d90 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
24da0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
24db0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
24dc0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
24dd0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
24de0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
24df0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
24e00 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
24e10 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
24e20 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
24e30 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
24e40 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
24e50 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
24e60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24e70 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
24e80 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
24e90 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
24ea0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
24eb0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
24ec0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
24ed0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
24ee0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
24ef0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
24f00 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
24f10 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
24f20 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
24f30 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
24f40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
24f50 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
24f60 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
24f70 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
24f80 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
24f90 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
24fa0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
24fb0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
24fc0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
24fd0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
24fe0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
24ff0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25000 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25010 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25020 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25030 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25040 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25050 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25060 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25070 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
25080 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
25090 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
250a0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
250b0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
250c0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
250d0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
250e0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
250f0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25100 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25110 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25120 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25130 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25140 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25150 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25160 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25170 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25180 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
25190 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
251a0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
251b0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
251c0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
251d0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
251e0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
251f0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25200 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25210 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25220 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25230 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25240 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25250 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25260 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25270 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
25280 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
25290 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
252a0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
252b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
252c0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
252d0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
252e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
252f0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
25300 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
25310 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
25320 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
25330 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
25340 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
25350 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
25360 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
25370 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
25380 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
25390 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
253a0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
253b0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
253c0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
253d0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
253e0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
253f0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
25400 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
25410 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
25420 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
25430 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
25440 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25450 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25460 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
25470 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
25480 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
25490 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
254a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
254b0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
254c0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
254d0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
254e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
254f0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
25500 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
25510 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
25520 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
25540 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
25550 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
25560 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25570 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25580 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
25590 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
255a0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
255b0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
255c0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
255d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
255e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
255f0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
25600 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
25610 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
25620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25630 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
25640 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
25650 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
25660 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
25670 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
25680 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
25690 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
256a0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
256b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
256c0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
256d0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
256e0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
256f0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
25700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25710 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
25720 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
25730 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
25740 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25750 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
25760 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
25770 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
25780 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25790 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
257a0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
257b0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
257c0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
257d0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
257e0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
257f0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
25800 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
25810 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
25820 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
25830 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
25840 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
25850 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
25860 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25870 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25880 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
25890 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
258a0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
258b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
258c0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
258d0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
258e0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
258f0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
25900 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
25910 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
25920 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
25930 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25940 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
25950 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
25960 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
25970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25980 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25990 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
259a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
259b0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
259c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
259d0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
259e0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
259f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
25a00 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
25a10 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
25a20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25a30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25a40 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
25a50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25a60 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25a70 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
25a80 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
25a90 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
25aa0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
25ab0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
25ac0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25ad0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25ae0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
25af0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25b00 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
25b10 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25b20 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
25b30 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
25b40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
25b50 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
25b60 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
25b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25b80 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
25b90 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
25ba0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
25bb0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
25bc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
25bd0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
25be0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
25bf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25c00 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
25c10 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
25c20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
25c30 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
25c40 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
25c50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
25c60 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
25c70 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
25c80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25c90 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
25ca0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
25cb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25cc0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
25cd0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
25ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25cf0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
25d00 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
25d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25d20 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
25d30 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
25d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25d50 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25d60 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
25d70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25d80 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
25d90 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
25da0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
25db0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
25dc0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
25dd0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
25de0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
25df0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
25e00 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
25e10 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
25e20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
25e30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
25e40 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
25e50 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
25e60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
25e70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
25e80 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
25e90 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
25ea0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
25eb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
25ec0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
25ed0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
25ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25ef0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
25f00 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
25f10 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
25f20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
25f30 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
25f40 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
25f50 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
25f60 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
25f70 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
25f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
25f90 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
25fa0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
25fb0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
25fc0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
25fd0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
25fe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25ff0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
26000 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
26010 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
26020 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
26030 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
26040 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
26050 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
26060 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
26070 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
26080 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
26090 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
260a0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
260b0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
260c0 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
260d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
260e0 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
260f0 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
26100 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
26110 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
26120 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
26130 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
26140 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
26150 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
26160 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
26170 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
26180 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
26190 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
261a0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
261b0 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
261c0 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
261d0 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
261e0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
261f0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
26200 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
26210 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26220 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
26230 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
26240 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
26250 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
26260 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
26270 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
26280 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
26290 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
262a0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
262b0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
262c0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
262d0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
262e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
262f0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
26300 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
26310 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
26320 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
26330 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
26340 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
26350 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
26360 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
26370 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
26380 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
26390 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
263a0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
263b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
263c0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
263d0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
263e0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
263f0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
26400 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
26410 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
26420 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
26430 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
26440 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
26450 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
26460 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
26470 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
26480 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
26490 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
264a0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
264b0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
264c0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
264d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
264e0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
264f0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
26500 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
26510 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
26520 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
26530 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26540 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
26550 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
26560 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
26570 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
26580 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
26590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
265a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
265b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
265c0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
265d0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
265e0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
265f0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
26600 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
26610 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
26620 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
26630 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
26640 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
26650 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
26660 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
26670 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
26680 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
26690 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
266a0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
266b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
266c0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
266d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
266e0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
266f0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
26700 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
26710 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
26720 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
26730 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
26740 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
26750 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
26760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
26770 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
26780 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
26790 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
267a0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
267b0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
267c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
267d0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
267e0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
267f0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
26800 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
26810 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
26820 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
26830 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
26840 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
26850 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
26860 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
26870 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
26880 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
26890 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
268a0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
268b0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
268c0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
268d0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
268e0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
268f0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
26900 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
26910 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
26920 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
26930 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
26940 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
26950 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
26960 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
26970 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
26980 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
26990 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
269a0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
269b0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
269c0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
269d0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
269e0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
269f0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
26a00 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
26a10 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
26a20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
26a30 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
26a40 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26a50 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
26a60 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
26a70 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
26a80 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
26a90 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
26aa0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
26ab0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
26ac0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
26ad0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
26ae0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
26af0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
26b00 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
26b10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
26b20 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
26b30 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
26b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
26b50 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
26b60 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
26b70 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
26b80 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
26b90 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
26ba0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
26bb0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
26bc0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
26bd0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
26be0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
26bf0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
26c00 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
26c10 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
26c20 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
26c30 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
26c40 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
26c50 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
26c60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
26c70 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT2] compile-t
26c80 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
26c90 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
26ca0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
26cb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
26cc0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26cd0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
26ce0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
26cf0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
26d00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
26d10 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
26d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
26d30 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
26d40 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26d50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
26d60 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26d70 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26d80 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26d90 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26da0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26db0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26dc0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
26dd0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26de0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26df0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26e00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26e10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26e20 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
26e30 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26e40 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26e50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26e60 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26e70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26e80 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26e90 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26ea0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26eb0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26ec0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26ed0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26ee0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26ef0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26f00 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26f10 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26f20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
26f30 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
26f40 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
26f50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26f60 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26f70 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
26f80 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26f90 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26fa0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26fb0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26fc0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26fd0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26fe0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27000 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27010 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27020 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27030 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27040 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27050 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27060 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
27070 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27080 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27090 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
270a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
270b0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
270c0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
270d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
270e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
270f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27100 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
27110 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27120 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
27130 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
27140 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
27150 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
27160 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
27170 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
27180 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
27190 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
271a0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
271b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
271c0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
271d0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
271e0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
271f0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
27200 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
27210 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
27220 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
27230 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
27240 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
27250 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
27260 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
27270 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
27280 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
27290 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
272a0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
272b0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
272c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
272d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
272e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
272f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27300 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27310 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27320 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
27330 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
27340 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27350 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
27360 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
27370 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
27380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27390 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
273a0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
273b0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
273c0 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
273d0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
273e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
273f0 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
27400 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
27410 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
27420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27430 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
27440 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
27450 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27460 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
27470 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
27480 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
27490 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
274a0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
274b0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
274c0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
274d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
274e0 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
274f0 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
27500 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
27510 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
27520 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
27530 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
27540 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
27550 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
27560 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
27570 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
27580 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
27590 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
275a0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
275b0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
275c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
275d0 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
275e0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
275f0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
27600 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27610 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
27620 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
27630 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
27640 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
27650 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
27660 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
27670 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
27680 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
27690 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
276a0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
276b0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
276c0 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
276d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
276e0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
276f0 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
27700 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
27710 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
27720 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
27730 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
27740 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
27750 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
27760 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
27770 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
27780 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
27790 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
277a0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
277b0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
277c0 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
277d0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
277e0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
277f0 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
27800 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
27810 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
27820 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
27830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
27840 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
27850 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
27860 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27870 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27880 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53  es on disk..*/.S
27890 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
278a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
278b0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
278c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
278d0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
278e0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
278f0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
27900 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
27910 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
27920 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
27930 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
27940 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
27950 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27960 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
27970 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
27980 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
27990 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
279a0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
279b0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
279c0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
279d0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
279e0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
279f0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
27a00 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
27a10 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
27a20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
27a30 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
27a40 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
27a50 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
27a60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
27a70 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
27a80 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
27a90 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
27aa0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
27ab0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
27ac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
27ad0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
27ae0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
27af0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
27b00 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
27b10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27b20 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
27b30 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
27b40 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
27b50 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
27b60 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
27b70 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
27b80 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
27b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
27ba0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
27bb0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
27bc0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
27bd0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
27be0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
27bf0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
27c00 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
27c10 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
27c20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27c30 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
27c40 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
27c50 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
27c60 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27c70 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
27c80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
27c90 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
27ca0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
27cb0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
27cc0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
27cd0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
27ce0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
27cf0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
27d00 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
27d10 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
27d20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
27d30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
27d40 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
27d50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
27d60 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
27d70 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
27d80 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
27d90 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
27da0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
27db0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27dc0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
27dd0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
27de0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
27df0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
27e00 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
27e10 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
27e20 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
27e30 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
27e40 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
27e50 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
27e60 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
27e70 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
27e80 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27e90 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
27ea0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
27eb0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
27ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27ed0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
27ee0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
27ef0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
27f00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
27f10 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
27f20 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
27f30 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
27f40 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
27f50 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27f60 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
27f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27f80 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
27f90 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
27fa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27fb0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
27fc0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
27fd0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
27fe0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
27ff0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
28000 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
28010 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28020 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
28030 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
28040 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
28050 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
28060 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28070 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
28080 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
28090 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
280a0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
280b0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
280c0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
280d0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
280e0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
280f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
28100 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
28110 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
28120 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28130 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
28140 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
28150 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
28160 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
28170 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
28180 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
281a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
281b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
281c0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
281d0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
281e0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
281f0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
28200 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
28210 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
28220 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
28230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
28240 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
28250 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
28260 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
28270 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
28280 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
28290 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
282a0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
282b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
282c0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
282d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
282e0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
282f0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
28300 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
28310 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
28320 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
28330 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
28340 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
28350 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
28360 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
28370 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
28380 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
28390 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
283a0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
283b0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
283c0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
283d0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
283e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
283f0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
28400 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
28410 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
28420 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
28430 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
28440 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
28450 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
28460 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
28470 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
28480 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
28490 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
284a0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
284b0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
284c0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
284d0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
284e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
284f0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
28500 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
28510 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
28520 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
28530 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
28540 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
28550 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
28560 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
28570 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
28580 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
28590 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
285a0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
285b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
285c0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
285d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
285e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
285f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28600 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
28610 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
28620 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
28630 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
28640 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
28650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28660 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
28670 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
28680 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28690 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
286a0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
286b0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
286c0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
286d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
286e0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
286f0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
28700 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
28710 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
28720 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
28730 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
28740 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
28750 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
28760 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
28770 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
28780 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
28790 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
287a0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
287b0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
287c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
287d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
287e0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
287f0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
28800 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
28810 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
28820 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
28830 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
28840 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
28850 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
28860 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
28870 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
28880 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28890 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
288a0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
288b0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
288c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
288d0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
288e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
288f0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
28900 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
28910 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
28920 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
28930 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
28940 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
28950 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
28960 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
28970 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
28980 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
28990 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
289a0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
289b0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
289c0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
289d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
289e0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
289f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
28a00 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
28a10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
28a20 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
28a30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
28a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
28a50 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
28a60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28a70 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
28a80 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
28a90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28aa0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
28ab0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
28ac0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
28ad0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
28ae0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
28af0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
28b00 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
28b10 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
28b20 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
28b30 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
28b40 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
28b50 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28b60 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
28b70 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
28b80 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28b90 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
28ba0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
28bb0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
28bc0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
28bd0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
28be0 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
28bf0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28c00 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
28c10 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
28c20 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
28c30 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
28c40 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
28c50 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
28c60 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
28c70 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
28c80 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
28c90 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
28ca0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
28cb0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
28cc0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
28cd0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
28ce0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28cf0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
28d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28d10 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
28d20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
28d30 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
28d40 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
28d50 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
28d60 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
28d70 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
28d80 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
28d90 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
28da0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
28db0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
28dc0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
28dd0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
28de0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
28df0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
28e00 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
28e10 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
28e20 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
28e30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
28e40 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
28e50 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
28e60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
28e70 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
28e80 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
28e90 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
28ea0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
28eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
28ec0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28ed0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
28ee0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
28ef0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28f00 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
28f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
28f20 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
28f30 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
28f40 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
28f50 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
28f60 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
28f70 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
28f80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
28f90 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
28fa0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
28fb0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
28fc0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
28fd0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
28fe0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
28ff0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29000 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
29010 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
29020 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
29030 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
29040 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
29050 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
29060 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
29070 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29080 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
29090 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
290a0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
290b0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
290c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
290d0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
290e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
290f0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
29100 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
29110 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
29120 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
29130 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
29140 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
29150 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
29160 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
29170 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
29180 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
29190 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
291a0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
291b0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
291c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
291d0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
291e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
291f0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
29200 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29210 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29220 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29230 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29240 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
29250 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29260 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
29270 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
29280 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29290 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
292a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
292b0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
292c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
292d0 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
292e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
292f0 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t, int);.SQLITE_
29300 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29310 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
29320 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
29330 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
29340 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29350 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
29360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29370 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
29380 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29390 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
293a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
293b0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
293c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
293d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
293e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
293f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29400 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29410 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29420 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
29430 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29440 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
29450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29460 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
29470 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
29480 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
29490 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
294a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
294b0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
294c0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
294d0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
294e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
294f0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
29500 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
29510 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
29520 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
29530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29540 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
29550 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
29560 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
29570 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
29580 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
29590 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
295a0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
295b0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
295c0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
295d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
295e0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
295f0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
29600 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
29610 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
29620 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
29630 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
29640 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
29650 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
29660 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
29670 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
29680 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
29690 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
296a0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
296b0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
296c0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
296d0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
296e0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
296f0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
29700 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
29710 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29720 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
29730 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29740 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29750 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
29760 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
29770 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29780 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
29790 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
297a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
297b0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
297c0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
297d0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
297e0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
297f0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
29800 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29810 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
29820 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29830 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
29840 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
29850 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
29860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29870 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
29880 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
29890 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
298a0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
298b0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
298c0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
298d0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
298e0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
298f0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
29900 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
29910 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
29920 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
29930 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
29940 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
29950 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
29960 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
29970 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
29980 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
29990 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
299a0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
299b0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
299c0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
299d0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
299e0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
299f0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
29a00 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
29a10 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
29a20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
29a30 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
29a40 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
29a50 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
29a60 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
29a70 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
29a80 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
29a90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
29aa0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
29ab0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
29ac0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
29ad0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
29ae0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
29af0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
29b00 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
29b10 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
29b20 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
29b30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
29b40 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
29b50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29b60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29b70 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29b90 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29ba0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29bb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29bc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29bd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
29be0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29bf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29c00 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29c10 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
29c20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
29c30 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
29c40 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
29c50 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
29c60 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
29c70 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29c80 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29c90 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29ca0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29cb0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29cc0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29cd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29ce0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29cf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
29d00 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
29d10 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
29d20 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
29d30 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
29d40 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
29d50 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
29d60 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
29d70 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
29d80 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
29d90 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
29da0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
29db0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29dc0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29dd0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29de0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29df0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29e00 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29e10 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29e20 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29e30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29e40 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29e50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29e70 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
29e80 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
29e90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
29ea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29eb0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
29ec0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
29ed0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
29ee0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
29ef0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
29f00 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
29f10 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
29f20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
29f30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
29f40 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
29f50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29f60 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
29f70 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
29f80 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
29f90 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
29fa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
29fc0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
29fd0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29fe0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
29ff0 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2a000 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2a010 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2a020 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a030 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2a040 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2a050 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2a060 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2a070 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2a080 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2a090 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2a0a0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2a0b0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2a0c0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2a0d0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2a0e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2a0f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2a100 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2a110 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a120 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2a130 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2a140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2a150 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2a160 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2a170 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a180 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2a190 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2a1a0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2a1b0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2a1c0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2a1d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2a1e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2a1f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2a200 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a210 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a220 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2a230 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2a240 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2a250 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2a260 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2a270 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2a280 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2a290 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2a2a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a2b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a2c0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2a2d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2a2e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2a2f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2a300 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2a310 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2a320 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2a330 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2a340 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2a350 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2a360 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2a370 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2a380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a390 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2a3a0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2a3b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2a3c0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2a3d0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2a3e0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2a3f0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2a400 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a410 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2a420 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2a430 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2a440 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2a450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a460 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2a470 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2a480 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2a490 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2a4a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2a4b0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2a4c0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2a4d0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2a4e0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2a4f0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2a500 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2a510 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2a520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2a530 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2a540 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2a550 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2a560 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2a570 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2a580 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2a590 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2a5a0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2a5b0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2a5c0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2a5d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2a5e0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2a5f0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2a600 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2a610 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2a620 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2a630 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a640 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a650 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2a660 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2a670 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a680 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a690 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2a6a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a6b0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2a6c0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2a6d0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2a6e0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2a6f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2a700 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2a710 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2a720 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2a730 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2a740 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2a750 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2a760 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2a770 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2a780 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2a790 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2a7a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2a7b0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2a7c0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2a7d0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2a7e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2a7f0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2a800 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2a810 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2a820 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2a830 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2a840 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2a850 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2a860 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2a870 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2a880 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2a890 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2a8a0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2a8b0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2a8c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2a8d0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2a8e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2a8f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2a900 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2a910 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2a920 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2a930 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2a940 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a950 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2a960 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2a970 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2a980 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2a990 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2a9a0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2a9b0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2a9c0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2a9d0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2a9e0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2a9f0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2aa00 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2aa10 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2aa20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2aa30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2aa40 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2aa50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aa60 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2aa70 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2aa80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2aa90 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2aaa0 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2aab0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2aac0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2aad0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2aae0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2aaf0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2ab00 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2ab10 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2ab20 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2ab30 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2ab40 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2ab50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ab60 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2ab70 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2ab80 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2ab90 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2aba0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2abb0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2abc0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2abd0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2abe0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2abf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2ac00 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2ac10 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2ac20 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2ac30 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2ac40 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2ac50 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2ac60 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2ac70 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2ac80 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2ac90 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2aca0 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2acb0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2acc0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2acd0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2ace0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2acf0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2ad00 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2ad10 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2ad20 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2ad30 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2ad40 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2ad50 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2ad60 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2ad70 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2ad80 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2ad90 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2ada0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2adb0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2adc0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2add0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ade0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2adf0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2ae00 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2ae10 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2ae20 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2ae30 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2ae40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2ae50 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2ae60 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2ae70 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2ae80 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2ae90 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2aea0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2aeb0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2aec0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2aed0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2aee0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2aef0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2af00 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2af10 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2af20 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2af30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2af40 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2af50 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2af60 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2af70 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2af80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2af90 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2afa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2afb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2afc0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2afd0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2afe0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2aff0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2b000 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2b010 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2b020 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2b030 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2b040 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b060 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2b070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b080 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2b090 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2b0b0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b0c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2b0d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b0e0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2b0f0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2b100 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2b110 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2b120 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b130 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2b140 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2b150 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2b160 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2b170 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2b180 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2b190 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2b1a0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2b1b0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2b1c0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2b1d0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2b1e0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2b1f0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2b200 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2b210 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2b220 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2b230 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b240 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2b250 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2b260 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2b270 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2b280 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2b290 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2b2a0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2b2b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2b2c0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2b2d0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b2e0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2b2f0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2b300 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2b310 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2b320 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2b330 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2b340 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2b350 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2b360 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2b370 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2b380 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2b390 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2b3a0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2b3b0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2b3c0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2b3d0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2b3e0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2b3f0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2b400 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2b410 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2b420 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2b430 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2b440 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2b450 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2b460 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2b470 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2b480 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2b490 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2b4a0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2b4b0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2b4c0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2b4d0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2b4e0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2b4f0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2b500 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2b510 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2b520 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2b530 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2b540 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2b550 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
2b560 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b570 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b580 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2b590 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b5a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2b5b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b5c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2b5d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b5e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b5f0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2b600 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2b610 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2b620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b630 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2b640 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2b650 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2b660 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2b670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b680 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2b690 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2b6a0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2b6b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2b6c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2b6d0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2b6e0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2b6f0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2b700 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2b710 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2b720 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2b730 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2b740 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2b750 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2b760 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2b770 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2b780 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2b790 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2b7a0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2b7b0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2b7c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b7d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2b7e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2b7f0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2b800 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2b810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b820 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b830 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2b840 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2b850 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2b860 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2b870 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2b880 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2b890 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2b8a0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2b8b0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2b8c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2b8d0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2b8e0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2b8f0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2b900 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2b910 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2b920 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2b930 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2b940 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2b950 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2b960 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2b970 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2b980 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2b990 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2b9a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2b9b0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2b9c0 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2b9d0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2b9e0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2b9f0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2ba00 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2ba10 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2ba20 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2ba30 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2ba40 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2ba50 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2ba60 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2ba70 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2ba80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2ba90 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2baa0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2bab0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2bac0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2bad0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2bae0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2baf0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2bb00 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2bb10 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2bb20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2bb30 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2bb40 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2bb50 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2bb60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2bb70 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2bb80 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2bb90 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2bba0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2bbb0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2bbc0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2bbd0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2bbe0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2bbf0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2bc00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2bc10 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2bc20 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2bc30 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2bc40 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2bc50 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2bc60 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2bc70 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2bc80 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2bc90 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2bca0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2bcb0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2bcc0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2bcd0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2bce0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2bcf0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2bd00 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2bd10 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2bd20 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2bd30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2bd40 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2bd50 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2bd60 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2bd70 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2bd80 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2bd90 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2bda0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2bdb0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2bdc0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2bdd0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2bde0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2bdf0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2be00 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2be10 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2be20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2be30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2be40 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2be50 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2be60 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2be70 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2be80 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2be90 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2bea0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2beb0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2bec0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2bed0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2bee0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2bef0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2bf00 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2bf10 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2bf20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2bf30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2bf40 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2bf50 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2bf60 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2bf70 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2bf80 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2bf90 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2bfa0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2bfb0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2bfc0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2bfd0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2bfe0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2bff0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2c000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2c010 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2c020 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2c030 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2c040 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2c050 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2c060 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2c070 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2c080 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2c090 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2c0a0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2c0b0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2c0c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2c0d0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2c0e0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2c0f0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2c100 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2c110 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2c120 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2c130 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2c140 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2c150 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2c160 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c170 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2c180 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2c190 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2c1a0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2c1b0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2c1c0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2c1d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2c1e0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2c1f0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2c200 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2c210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c220 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2c230 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2c240 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2c250 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2c260 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2c270 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2c280 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2c290 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2c2a0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2c2b0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2c2c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2c2d0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2c2e0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2c2f0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2c300 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2c310 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2c320 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2c330 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2c340 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2c350 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2c360 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2c370 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2c380 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2c390 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2c3a0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2c3b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2c3c0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2c3d0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2c3e0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2c3f0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2c400 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2c410 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2c420 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2c430 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2c440 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2c450 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2c460 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2c470 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2c480 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2c490 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2c4a0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2c4b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2c4c0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2c4d0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2c4e0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2c4f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2c500 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c510 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2c520 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2c530 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2c540 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2c550 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2c560 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2c570 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2c580 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2c590 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2c5a0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2c5b0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2c5c0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2c5d0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2c5e0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2c5f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2c600 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2c610 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c620 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2c630 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2c640 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2c650 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2c660 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2c670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c680 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2c690 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2c6a0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2c6b0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2c6c0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2c6d0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2c6e0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2c6f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2c700 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2c710 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c720 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2c730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2c740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c750 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2c760 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2c770 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2c780 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c790 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2c7a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c7b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c7c0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2c7d0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2c7e0 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2c7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2c800 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2c810 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2c820 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2c830 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2c840 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2c850 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2c860 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2c870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2c880 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2c890 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2c8a0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2c8b0 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2c8c0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c8d0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2c8e0 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2c8f0 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2c900 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nter..**.** See 
2c910 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2c920 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2c930 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c940 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2c950 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2c960 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c970 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2c980 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2c990 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2c9a0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2c9b0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2c9c0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2c9d0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2c9e0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2c9f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2ca00 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2ca10 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2ca20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2ca30 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2ca40 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2ca50 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2ca60 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2ca70 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2ca80 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2ca90 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2caa0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2cab0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2cac0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2cad0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2cae0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2caf0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2cb00 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2cb10 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2cb20 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2cb30 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2cb40 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2cb50 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2cb60 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2cb70 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2cb80 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2cb90 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2cba0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2cbb0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2cbc0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2cbd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2cbe0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2cbf0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2cc00 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2cc10 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2cc20 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2cc30 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2cc40 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2cc50 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2cc60 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2cc70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2cc80 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2cc90 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2cca0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2ccb0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2ccc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2ccd0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2cce0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2ccf0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2cd00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2cd10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2cd20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2cd30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2cd40 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2cd50 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2cd60 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2cd70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2cd80 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2cd90 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2cda0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2cdb0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2cdc0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2cdd0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2cde0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2cdf0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2ce00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2ce10 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2ce20 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2ce30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2ce40 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2ce50 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2ce60 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2ce70 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2ce80 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2ce90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2cea0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2ceb0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2cec0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2ced0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2cee0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2cef0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2cf00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2cf10 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2cf20 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2cf30 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2cf40 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2cf50 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2cf60 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2cf70 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2cf80 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2cf90 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2cfa0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2cfb0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2cfc0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2cfd0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2cfe0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2cff0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2d000 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2d010 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2d020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d030 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2d040 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2d050 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2d060 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2d070 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2d080 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2d090 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2d0a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2d0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2d0c0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2d0d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d0e0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2d0f0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2d100 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2d110 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2d120 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2d130 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2d140 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2d150 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2d160 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d170 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2d180 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2d190 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2d1a0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2d1b0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2d1c0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2d1d0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2d1e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2d1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d200 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2d210 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2d220 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2d230 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2d240 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2d250 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2d260 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2d270 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2d280 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2d290 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2d2a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2d2b0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2d2c0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2d2d0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2d2e0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2d2f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2d300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d310 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2d320 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2d330 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2d340 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2d350 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2d360 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2d370 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2d380 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2d390 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2d3a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2d3b0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2d3c0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2d3d0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2d3e0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2d3f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2d400 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2d410 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2d420 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2d430 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d440 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2d450 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2d460 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d470 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2d480 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2d490 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d4a0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2d4b0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2d4c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2d4d0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2d4e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d4f0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2d500 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2d510 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2d520 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2d530 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2d540 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2d550 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2d560 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2d570 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d580 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2d590 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2d5a0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2d5b0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2d5c0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2d5d0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2d5e0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2d5f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2d600 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2d610 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2d620 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d630 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2d640 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d650 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2d660 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2d670 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2d680 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2d690 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2d6a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2d6b0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2d6c0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2d6d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d6e0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2d6f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2d700 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d710 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2d720 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2d730 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2d740 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2d750 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2d760 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2d770 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2d780 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2d790 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2d7a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2d7b0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2d7c0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2d7d0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2d7e0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2d7f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d800 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2d810 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d820 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2d830 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d840 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2d850 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2d860 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2d870 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2d880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d890 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2d8a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d8b0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2d8c0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2d8d0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2d8e0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2d8f0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2d900 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2d910 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d920 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d930 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2d940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d950 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2d960 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2d970 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2d980 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2d990 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2d9a0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2d9b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d9d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2d9e0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2d9f0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2da00 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2da10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
2da20 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2da30 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2da40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2da50 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2da60 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2da70 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2da80 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2da90 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2daa0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2dab0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2dac0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2dad0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2dae0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2daf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2db00 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2db10 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2db20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2db30 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2db40 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2db50 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2db60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2db70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2db80 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2db90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2dba0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2dbb0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2dbc0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2dbd0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2dbe0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2dbf0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2dc00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2dc10 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2dc20 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2dc30 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2dc40 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2dc50 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2dc60 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2dc70 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2dc80 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2dc90 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2dca0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2dcb0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2dcc0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2dcd0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2dce0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2dcf0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2dd00 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2dd10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2dd20 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2dd30 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2dd40 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2dd50 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2dd60 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2dd70 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2dd80 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2dd90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2dda0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2ddb0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2ddc0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2ddd0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2dde0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2ddf0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2de00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2de10 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2de20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2de30 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2de40 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2de50 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2de60 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2de70 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2de80 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2de90 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2dea0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2deb0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2dec0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2ded0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
2dee0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2def0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2df00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2df10 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2df20 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2df30 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2df40 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2df50 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2df60 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2df70 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2df80 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2df90 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2dfa0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2dfb0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2dfc0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2dfd0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2dfe0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
2dff0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
2e000 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e010 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
2e020 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2e030 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2e040 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2e050 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2e060 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2e070 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
2e080 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2e090 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2e0a0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
2e0b0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2e0c0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2e0d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e0e0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
2e0f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e100 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e110 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2e120 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e130 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e140 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2e150 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2e160 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
2e170 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2e180 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e190 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2e1a0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
2e1b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2e1c0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2e1d0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2e1e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2e1f0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2e200 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2e210 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2e220 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2e230 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2e240 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2e250 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2e260 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2e270 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2e280 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2e290 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2e2a0 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2e2b0 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2e2c0 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2e2d0 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2e2e0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2e2f0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2e300 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2e310 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2e320 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2e330 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2e340 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2e350 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2e360 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2e370 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2e380 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2e390 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2e3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e3b0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2e3c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2e3d0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2e3e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e3f0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2e400 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2e410 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2e420 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2e430 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2e440 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2e450 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2e460 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2e470 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2e480 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2e490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e4a0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2e4b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e4c0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2e4d0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2e4e0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2e4f0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2e500 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2e510 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2e520 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2e530 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2e540 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2e550 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2e560 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2e570 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e580 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2e590 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2e5a0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2e5b0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2e5c0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2e5d0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2e5e0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2e5f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e600 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2e610 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2e620 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2e630 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2e640 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2e650 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2e660 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2e670 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2e680 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2e690 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2e6a0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2e6b0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2e6c0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2e6d0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2e6e0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2e6f0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2e700 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2e710 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2e720 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2e730 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2e740 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2e750 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2e760 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2e770 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2e780 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2e790 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2e7a0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2e7b0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2e7c0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2e7d0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2e7e0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2e7f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2e800 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2e810 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2e820 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2e830 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2e840 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2e850 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2e860 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2e870 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2e880 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2e890 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e8a0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2e8b0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2e8c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2e8d0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e8e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2e8f0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2e900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e910 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2e920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e930 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2e940 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2e950 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2e960 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2e970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e980 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2e990 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2e9a0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2e9b0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2e9c0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2e9d0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2e9e0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2e9f0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2ea00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ea10 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2ea20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ea30 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2ea40 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2ea50 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2ea60 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2ea70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2ea80 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2ea90 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2eaa0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2eab0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2eac0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2ead0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2eae0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2eaf0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2eb00 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2eb10 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2eb20 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2eb30 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2eb40 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2eb50 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2eb60 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2eb70 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2eb80 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2eb90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2eba0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2ebb0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ebc0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2ebd0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2ebe0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2ebf0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2ec00 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2ec10 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2ec20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2ec30 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2ec40 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2ec50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2ec60 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2ec70 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2ec80 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2ec90 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2eca0 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2ecb0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2ecc0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2ecd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2ece0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2ecf0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2ed00 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2ed10 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2ed20 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2ed30 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2ed40 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2ed50 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2ed60 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2ed70 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2ed80 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2ed90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2eda0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2edb0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2edc0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
2edd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2ede0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2edf0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2ee00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2ee10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ee20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ee30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ee40 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ee50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ee60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ee70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ee80 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ee90 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69  _API double sqli
2eea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2eeb0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2eec0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2eed0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2eee0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2eef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ef00 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ef10 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
2ef20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ef30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2ef40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ef50 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ef60 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2ef70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ef80 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2ef90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2efa0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2efb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2efc0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2efd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2efe0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2eff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f000 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2f010 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f020 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2f030 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2f040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2f050 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f060 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2f070 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2f080 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2f090 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2f0a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f0b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2f0c0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2f0d0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2f0e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f0f0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
2f100 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2f110 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2f120 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
2f130 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
2f140 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
2f150 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
2f160 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
2f170 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f180 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
2f190 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
2f1a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2f1b0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
2f1c0 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
2f1d0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
2f1e0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
2f1f0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
2f200 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2f210 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2f220 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
2f230 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f240 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
2f250 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2f260 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2f270 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
2f280 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
2f290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f2a0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
2f2b0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
2f2c0 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
2f2d0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
2f2e0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
2f2f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
2f300 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
2f310 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
2f320 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
2f330 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
2f340 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
2f350 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
2f360 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
2f370 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
2f380 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f390 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
2f3a0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
2f3b0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
2f3c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
2f3d0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
2f3e0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
2f3f0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
2f400 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
2f410 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
2f420 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
2f430 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
2f440 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
2f450 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
2f460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2f470 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2f480 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
2f490 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
2f4a0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2f4b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2f4c0 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
2f4d0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
2f4e0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
2f4f0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
2f500 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
2f510 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
2f520 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
2f530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f540 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2f550 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f570 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2f580 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2f590 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
2f5a0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2f5b0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2f5c0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2f5d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2f5e0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2f5f0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2f600 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2f610 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2f620 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
2f630 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
2f640 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
2f650 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
2f660 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
2f670 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2f680 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
2f690 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
2f6a0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
2f6b0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
2f6c0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
2f6d0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
2f6e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2f6f0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f700 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
2f710 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2f720 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
2f730 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2f740 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2f750 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
2f760 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2f770 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f780 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2f790 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f7a0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2f7b0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2f7c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2f7d0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
2f7e0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2f7f0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2f800 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2f810 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
2f820 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2f830 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2f840 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2f850 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2f860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f870 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2f880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f890 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
2f8a0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
2f8b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2f8c0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2f8d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2f8e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2f8f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2f900 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2f910 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2f920 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2f930 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
2f940 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
2f950 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
2f960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f970 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
2f980 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
2f990 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2f9a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2f9b0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2f9c0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2f9d0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2f9e0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2f9f0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2fa00 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2fa10 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2fa20 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2fa30 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2fa40 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2fa50 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2fa60 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2fa70 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2fa80 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2fa90 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2faa0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2fab0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2fac0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2fad0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2fae0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2faf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2fb00 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2fb10 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2fb20 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2fb30 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2fb40 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2fb50 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2fb60 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2fb70 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2fb80 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2fb90 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2fba0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2fbb0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2fbc0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2fbd0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2fbe0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2fbf0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2fc00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2fc10 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2fc20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2fc30 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2fc40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fc50 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2fc60 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2fc70 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2fc80 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2fc90 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2fca0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2fcb0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2fcc0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2fcd0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2fce0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2fcf0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2fd00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fd10 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2fd20 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2fd30 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2fd40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2fd50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fd60 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2fd70 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2fd80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2fd90 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2fda0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2fdb0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2fdc0 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2fdd0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2fde0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2fdf0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2fe00 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2fe10 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2fe20 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2fe30 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2fe40 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2fe50 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2fe60 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2fe70 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2fe80 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2fe90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2fea0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2feb0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2fec0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2fed0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2fee0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2fef0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2ff00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2ff10 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2ff20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2ff30 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2ff40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2ff50 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2ff60 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2ff70 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2ff80 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2ff90 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2ffa0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2ffb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2ffc0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2ffd0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2ffe0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2fff0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
30000 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
30010 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
30020 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
30030 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
30040 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
30050 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
30060 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
30070 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
30080 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
30090 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
300a0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
300b0 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
300c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
300d0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
300e0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
300f0 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
30100 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
30110 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
30120 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
30130 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
30140 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
30150 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
30160 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
30170 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
30180 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
30190 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
301a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
301b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
301c0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
301d0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
301e0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
301f0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
30200 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
30210 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
30220 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30230 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
30240 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
30250 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
30260 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
30270 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
30280 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
30290 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
302a0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
302b0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
302c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
302d0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
302e0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
302f0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
30300 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
30310 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
30320 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
30330 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
30340 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
30350 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
30360 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
30370 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30380 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
30390 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
303a0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
303b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
303c0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
303d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
303e0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
303f0 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
30400 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
30410 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
30420 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
30430 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
30440 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
30450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30460 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
30470 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
30480 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
30490 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
304a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
304b0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
304c0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
304d0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
304e0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
304f0 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
30500 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
30510 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
30520 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
30530 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30540 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
30550 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
30560 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
30570 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
30580 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
30590 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
305a0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
305b0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
305c0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
305d0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
305e0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
305f0 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
30600 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
30610 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30620 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
30630 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
30640 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
30650 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
30660 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30670 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
30680 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
30690 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
306a0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
306b0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
306c0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
306d0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
306e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
306f0 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
30700 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
30710 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
30720 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
30730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30740 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
30750 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
30760 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
30770 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
30780 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
30790 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
307a0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
307b0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
307c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
307d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
307e0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
307f0 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
30800 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30810 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30820 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
30830 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
30840 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
30850 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
30860 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
30870 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
30880 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
30890 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
308a0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
308b0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
308c0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
308d0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
308e0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
308f0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
30900 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
30910 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
30920 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
30930 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
30940 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
30950 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
30960 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
30970 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
30980 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
30990 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
309a0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
309b0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
309c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
309d0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
309e0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
309f0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
30a00 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
30a10 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
30a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
30a30 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
30a40 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
30a50 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
30a60 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
30a70 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
30a80 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
30a90 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30aa0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
30ab0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
30ac0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
30ad0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
30ae0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
30af0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
30b00 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
30b10 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
30b20 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
30b30 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
30b40 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
30b50 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
30b60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30b70 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
30b80 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
30b90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30ba0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
30bb0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
30bc0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
30bd0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
30be0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
30bf0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
30c00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30c10 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
30c20 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
30c30 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
30c40 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
30c50 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
30c60 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
30c70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30c80 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30c90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30ca0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30cb0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
30cc0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
30cd0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
30ce0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
30cf0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
30d00 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30d10 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30d20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30d30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30d40 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30d50 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30d60 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30d70 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
30d80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30d90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30da0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
30db0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
30dc0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
30dd0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
30de0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
30df0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
30e00 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
30e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30e20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30e30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
30e40 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
30e50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30e60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30e70 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30e80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
30e90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30ea0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30eb0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
30ec0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
30ed0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
30ee0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
30ef0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
30f00 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
30f10 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
30f20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30f30 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
30f40 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
30f50 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
30f60 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30f70 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30f80 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
30f90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30fa0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
30fb0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
30fc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30fd0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
30fe0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
30ff0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
31000 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
31010 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
31020 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
31030 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
31040 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
31050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31060 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
31070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31080 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
31090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
310a0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
310b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
310c0 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
310d0 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
310e0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
310f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
31100 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
31110 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
31120 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
31130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31140 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
31150 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
31160 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31170 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
31180 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
31190 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
311a0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
311b0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
311c0 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
311d0 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
311e0 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
311f0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
31200 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
31210 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
31220 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
31230 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
31240 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
31250 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
31260 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
31270 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
31280 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
31290 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
312a0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
312b0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
312c0 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
312d0 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
312e0 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
312f0 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
31300 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
31310 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50  ECATED.SQLITE_AP
31320 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
31330 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31340 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
31350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
31370 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31380 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
31390 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
313a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
313b0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
313c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
313d0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
313e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
313f0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
31400 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
31410 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31420 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
31430 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
31440 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31450 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
31460 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
31470 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
31480 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
31490 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
314a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
314b0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
314c0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
314d0 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
314e0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
314f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31500 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
31510 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
31520 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
31530 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
31540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
31550 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
31560 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
31570 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
31580 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
31590 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
315a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
315b0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
315c0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
315d0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
315e0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
315f0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
31600 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
31610 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
31620 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
31630 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31640 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31650 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31660 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
31670 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
31680 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
31690 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
316a0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
316b0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
316c0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
316d0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
316e0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
316f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31700 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31710 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
31720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31730 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
31740 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
31750 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31760 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
31770 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
31780 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
31790 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
317a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
317b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
317c0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
317d0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
317e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
317f0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
31800 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
31810 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
31820 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
31830 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31840 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
31850 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
31860 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
31870 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31880 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
31890 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
318a0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
318b0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
318c0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
318d0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
318e0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
318f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31900 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
31910 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
31920 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
31930 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
31940 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
31950 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
31960 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
31970 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
31980 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
31990 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
319a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
319b0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
319c0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
319d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
319e0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
319f0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
31a00 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
31a10 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
31a20 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
31a30 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
31a40 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
31a50 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
31a60 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
31a70 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
31a80 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
31a90 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
31aa0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
31ab0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
31ac0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
31ad0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
31ae0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
31af0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
31b00 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
31b10 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
31b20 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
31b30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
31b40 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
31b50 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
31b60 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
31b70 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
31b80 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
31b90 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
31ba0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
31bb0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
31bc0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
31bd0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
31be0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
31bf0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
31c00 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
31c10 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
31c20 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
31c30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
31c40 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
31c50 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
31c60 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
31c70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
31c80 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
31c90 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
31ca0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31cb0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
31cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31cd0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
31ce0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
31cf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
31d00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
31d10 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
31d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31d30 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
31d40 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
31d50 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
31d60 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
31d70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
31d80 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
31d90 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31da0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
31db0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31dc0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
31dd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31de0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
31df0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
31e00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31e10 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
31e20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31e30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31e40 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31e50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31e60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31e70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
31e80 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
31e90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
31ea0 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
31eb0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
31ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31ed0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
31ef0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31f00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
31f10 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
31f20 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
31f30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31f40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
31f50 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
31f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31f70 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
31f80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
31f90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31fa0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31fc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31fd0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31fe0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
31ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32000 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32010 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32020 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
32030 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
32040 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
32050 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
32060 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32070 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
32080 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
32090 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
320a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
320b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
320c0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
320d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
320e0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
320f0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
32100 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
32110 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
32120 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
32130 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
32140 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
32150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
32160 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
32170 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32180 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
32190 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
321a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
321b0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
321c0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
321d0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
321e0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
321f0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
32200 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
32210 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
32220 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
32230 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
32240 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
32250 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32260 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
32270 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
32280 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
32290 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
322a0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
322b0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
322c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
322d0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
322e0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
322f0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
32300 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
32310 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
32320 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
32330 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
32340 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
32350 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
32360 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
32370 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
32380 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
32390 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
323a0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
323b0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
323c0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
323d0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
323e0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
323f0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
32400 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
32410 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32420 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
32430 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
32440 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
32450 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
32460 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
32470 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
32480 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
324a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
324b0 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
324c0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
324d0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
324e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
324f0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
32500 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
32510 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
32520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
32530 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32540 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
32550 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
32560 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
32570 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
32580 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
32590 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
325a0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
325b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
325c0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
325d0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
325e0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
325f0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
32600 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
32610 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
32620 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
32630 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
32640 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
32650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
32660 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
32670 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32680 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
32690 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
326a0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
326b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
326c0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
326d0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
326e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
326f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
32700 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
32710 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32720 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
32730 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
32740 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
32750 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
32760 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
32770 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32780 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32790 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
327a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
327b0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
327c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
327d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
327e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
327f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
32800 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
32810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32820 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
32830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
32840 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
32850 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
32860 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
32870 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32880 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32890 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
328a0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
328b0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
328c0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
328d0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
328e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
328f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32900 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32910 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32920 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32930 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32940 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32950 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32960 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32970 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
32980 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32990 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
329a0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
329b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
329c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
329d0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
329e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
329f0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
32a00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32a20 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
32a30 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
32a40 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
32a50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
32a60 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
32a70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
32a80 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
32a90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
32aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32ab0 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
32ac0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
32ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
32ae0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
32af0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
32b00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32b10 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
32b20 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
32b30 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
32b40 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
32b50 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
32b60 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
32b70 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
32b80 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
32b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32bb0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32bc0 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
32bd0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
32be0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
32bf0 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
32c00 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
32c10 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
32c20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
32c30 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
32c40 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
32c50 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
32c60 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
32c70 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32c80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
32c90 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32ca0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
32cb0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
32cc0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
32cd0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
32ce0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
32cf0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
32d00 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
32d10 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
32d20 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
32d30 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
32d40 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
32d50 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
32d60 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
32d70 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
32d80 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
32d90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32da0 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
32db0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
32dc0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
32dd0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
32de0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
32df0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
32e00 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
32e10 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
32e20 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32e30 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
32e40 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
32e50 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
32e60 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
32e70 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
32e80 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
32e90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
32ea0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32eb0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
32ec0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32ed0 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
32ee0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
32ef0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
32f00 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
32f10 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
32f20 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
32f30 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
32f40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32f50 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
32f60 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
32f70 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
32f80 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
32f90 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
32fa0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
32fb0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32fc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
32fd0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
32fe0 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
32ff0 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
33000 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
33010 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
33020 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
33030 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
33040 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33050 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
33060 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
33070 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
33080 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
33090 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
330a0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
330b0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
330c0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
330d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
330e0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
330f0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
33100 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
33110 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
33120 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
33130 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
33140 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
33150 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
33160 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
33170 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
33180 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
33190 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
331a0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
331b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
331c0 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
331d0 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
331e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
331f0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
33200 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
33210 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
33220 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
33230 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
33240 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
33250 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
33260 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
33270 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
33280 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
33290 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
332a0 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
332b0 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
332c0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
332d0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
332e0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
332f0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
33300 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
33310 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
33320 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
33330 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
33340 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
33350 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
33360 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
33370 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
33380 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
33390 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
333a0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
333b0 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
333c0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
333d0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
333e0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
333f0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
33400 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
33410 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
33420 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
33430 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
33440 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
33450 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33460 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
33470 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65   void sqlite3_se
33480 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33490 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
334a0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
334b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
334c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
334d0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
334e0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
334f0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
33500 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
33510 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
33520 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
33530 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
33540 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
33550 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
33560 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
33570 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
33580 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
33590 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
335a0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
335b0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
335c0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
335d0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
335e0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
335f0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
33600 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
33610 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
33620 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
33630 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
33640 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33650 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
33660 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
33670 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
33680 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
33690 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
336a0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
336b0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
336c0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
336d0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
336e0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
336f0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
33700 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
33710 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
33720 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
33730 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
33740 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
33750 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33760 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
33770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
33780 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
33790 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
337a0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
337b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
337c0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
337d0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
337e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
337f0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
33800 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
33810 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
33820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33830 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
33840 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
33850 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
33860 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
33870 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
33880 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
33890 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
338a0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
338b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
338c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
338d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
338e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
338f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
33900 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
33910 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
33920 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
33930 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
33940 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
33950 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
33960 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
33970 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33980 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
33990 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
339a0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
339b0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
339c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
339d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
339e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
339f0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
33a00 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
33a10 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
33a20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33a30 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
33a40 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
33a50 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
33a60 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
33a70 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
33a80 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
33a90 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
33aa0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
33ab0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
33ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
33ad0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
33ae0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
33af0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
33b00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33b10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33b20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
33b30 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
33b40 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
33b50 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
33b60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
33b70 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33b80 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
33b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
33ba0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
33bb0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
33bc0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
33bd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33be0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
33bf0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
33c00 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
33c10 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
33c20 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
33c30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33c40 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33c50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33c60 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
33c70 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
33c80 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
33c90 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
33ca0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
33cb0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
33cc0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
33cd0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
33ce0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
33cf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33d00 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
33d10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33d20 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
33d30 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
33d40 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
33d50 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
33d60 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
33d70 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
33d80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33d90 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
33da0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
33db0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
33dc0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
33dd0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
33de0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
33df0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
33e00 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
33e10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
33e20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33e30 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33e40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33e50 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
33e60 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
33e70 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
33e80 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
33e90 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
33ea0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
33eb0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
33ec0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
33ed0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
33ee0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
33ef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33f00 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
33f10 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
33f20 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
33f30 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
33f40 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
33f50 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
33f60 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
33f70 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
33f80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33f90 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33fb0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
33fc0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
33fd0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
33fe0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33ff0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
34000 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
34010 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
34020 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
34030 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
34040 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
34050 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
34060 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
34070 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34080 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
34090 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
340a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
340b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
340c0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
340d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
340e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
340f0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
34100 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
34110 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
34120 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
34130 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
34140 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
34150 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34160 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
34170 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
34180 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
34190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
341a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
341b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
341c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
341d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
341e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
341f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
34200 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
34210 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
34220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34230 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
34240 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
34250 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
34260 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
34270 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
34280 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
34290 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
342a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342b0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
342c0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
342d0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
342e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
342f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34300 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
34310 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34320 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34330 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34340 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34350 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
34360 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34370 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34380 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
34390 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
343a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
343b0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
343c0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
343d0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
343e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
343f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34400 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
34410 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34420 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34430 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34440 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34450 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
34460 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34470 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
34480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34490 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
344a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
344b0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
344c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
344d0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
344e0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
344f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
34500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34510 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34520 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
34530 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
34540 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
34550 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
34560 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
34570 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
34580 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
34590 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
345a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
345b0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
345c0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
345d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
345e0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
345f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
34600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34610 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34620 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34630 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34640 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34650 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34660 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
34670 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
34680 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
34690 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
346a0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
346b0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
346c0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
346d0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
346e0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
346f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
34700 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
34710 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
34720 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
34730 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
34740 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
34750 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
34760 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34770 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
34780 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34790 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
347a0 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
347b0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
347c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
347d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
347e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
347f0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34800 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
34810 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
34820 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
34830 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
34840 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
34850 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
34860 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
34870 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
34880 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
34890 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
348a0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
348b0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
348c0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
348d0 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
348e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
348f0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34900 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34910 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
34920 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
34930 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
34940 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
34950 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
34960 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
34970 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
34980 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
34990 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
349a0 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
349b0 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
349c0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
349d0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
349e0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
349f0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
34a00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
34a10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34a20 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
34a30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34a40 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
34a50 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
34a60 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
34a70 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
34a80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
34a90 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
34aa0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
34ab0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
34ac0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
34ad0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
34ae0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34af0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
34b00 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34b10 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
34b20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34b30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34b40 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
34b50 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34b70 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
34b80 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
34b90 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
34ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34bb0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
34bc0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
34bd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34be0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
34bf0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34c00 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
34c10 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
34c20 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
34c30 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
34c40 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
34c50 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
34c60 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
34c70 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
34c80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34c90 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
34ca0 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
34cb0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
34cc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34cd0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
34ce0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
34cf0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
34d00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34d10 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
34d20 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
34d30 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
34d40 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
34d50 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
34d60 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
34d70 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
34d80 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
34d90 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
34da0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34db0 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
34dc0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
34dd0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
34de0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
34df0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
34e00 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
34e10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34e20 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
34e30 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
34e40 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
34e50 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
34e60 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
34e70 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
34e80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34e90 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
34ea0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34eb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34ed0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
34ee0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
34ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34f00 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
34f10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34f20 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
34f30 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
34f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34f50 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
34f60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34f70 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34f80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34f90 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
34fa0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
34fb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34fd0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
34fe0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
34ff0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35000 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35010 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
35020 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  xt*, int);.SQLIT
35030 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35040 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
35050 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35060 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
35070 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35080 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35090 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
350a0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
350b0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
350c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
350d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
350e0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
350f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35100 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35110 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35120 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
35130 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35140 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
35150 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
35160 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35170 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35180 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
35190 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
351a0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
351b0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
351c0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
351d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
351e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
351f0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35200 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
35210 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
35220 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35230 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
35240 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
35250 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
35260 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35270 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
35280 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
35290 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
352a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
352b0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
352c0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
352d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
352e0 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
352f0 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
35300 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
35310 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
35320 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35330 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
35340 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
35350 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
35360 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
35370 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
35380 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
35390 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
353a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
353b0 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
353c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
353d0 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
353e0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
353f0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
35400 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35410 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
35420 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
35430 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
35440 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
35450 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
35460 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
35470 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
35480 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
35490 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
354a0 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
354b0 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
354c0 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
354d0 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
354e0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
354f0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35500 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
35510 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
35520 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
35530 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
35540 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
35550 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
35560 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
35570 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
35580 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
35590 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
355a0 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
355b0 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
355c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
355d0 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
355e0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
355f0 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
35600 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
35610 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
35620 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
35630 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
35640 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
35650 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
35660 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
35670 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
35680 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
35690 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
356a0 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
356b0 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
356c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
356d0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
356e0 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
356f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35700 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
35710 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
35720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35730 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
35740 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
35750 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
35760 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
35770 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
35780 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35790 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
357a0 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
357b0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
357c0 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
357d0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
357e0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
357f0 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
35800 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
35810 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
35820 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
35830 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
35840 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
35850 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
35860 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
35870 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
35880 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
35890 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
358a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
358b0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
358c0 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
358d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
358e0 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
358f0 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
35900 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
35910 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
35920 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
35930 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
35940 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35950 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
35960 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
35970 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
35980 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
35990 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
359a0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
359b0 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
359c0 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
359d0 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
359e0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
359f0 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
35a00 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
35a10 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
35a20 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
35a30 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
35a40 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
35a50 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
35a60 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
35a70 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
35a80 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
35a90 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
35aa0 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
35ab0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
35ac0 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
35ad0 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
35ae0 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
35af0 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
35b00 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
35b10 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
35b20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
35b30 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
35b40 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
35b50 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
35b60 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
35b70 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
35b80 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
35b90 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
35ba0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
35bb0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35bc0 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
35bd0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
35be0 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
35bf0 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
35c00 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
35c10 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
35c20 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
35c30 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
35c40 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
35c50 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
35c60 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
35c70 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
35c80 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
35c90 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
35ca0 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
35cb0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
35cc0 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
35cd0 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
35ce0 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
35cf0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35d00 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
35d10 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
35d20 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
35d30 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
35d40 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
35d50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35d60 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
35d70 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
35d80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35d90 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
35da0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
35db0 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
35dc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
35dd0 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
35de0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
35df0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
35e00 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
35e10 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
35e20 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
35e30 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
35e40 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
35e50 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
35e60 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
35e70 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
35e80 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
35e90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
35ea0 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
35eb0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
35ec0 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
35ed0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
35ee0 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
35ef0 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
35f00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35f10 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
35f20 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
35f30 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
35f40 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
35f50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
35f60 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
35f70 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
35f80 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
35f90 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
35fa0 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
35fb0 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
35fc0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35fd0 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
35fe0 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
35ff0 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
36000 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
36010 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
36020 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
36030 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
36040 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
36050 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
36060 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
36070 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
36080 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
36090 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
360a0 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
360b0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
360c0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
360d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
360e0 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
360f0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36100 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53  eeded16()]..*/.S
36110 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
36120 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36130 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
36140 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36150 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
36160 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
36170 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
36180 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
36190 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
361a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
361b0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
361c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
361d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
361e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
361f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
36200 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
36210 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
36220 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
36230 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
36240 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
36250 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
36260 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
36270 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
36280 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36290 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
362a0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
362b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
362c0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
362d0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
362e0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
362f0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
36300 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
36310 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
36320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36330 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
36340 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
36350 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
36360 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
36370 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
36380 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
36390 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
363a0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
363b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
363c0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
363d0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
363e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
363f0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
36400 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
36410 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
36420 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
36430 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
36440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
36450 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
36460 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
36470 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36480 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
36490 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
364a0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
364b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
364c0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
364d0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
364e0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
364f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
36500 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
36510 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
36520 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
36530 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
36540 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
36550 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
36560 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
36570 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
36580 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
36590 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
365a0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
365b0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
365c0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
365d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
365e0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
365f0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
36600 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
36610 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36620 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
36630 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36640 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
36650 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
36660 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
36670 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
36680 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
36690 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
366a0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
366b0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
366c0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
366d0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
366e0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
366f0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
36700 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
36710 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
36720 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
36730 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
36740 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
36750 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
36760 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
36770 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
36780 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
36790 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
367a0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
367b0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
367c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
367d0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
367e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
367f0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
36800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
36810 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36820 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
36830 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36840 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
36850 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36860 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
36870 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
36880 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
36890 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51  nst char*).);.SQ
368a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
368b0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
368c0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
368d0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
368e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
368f0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
36900 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
36910 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
36920 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
36930 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
36940 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
36950 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
36960 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
36970 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
36980 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
36990 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
369a0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
369b0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
369c0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
369d0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
369e0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
369f0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
36a00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36a10 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
36a20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36a30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
36a40 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
36a50 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
36a60 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
36a70 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
36a80 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
36a90 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
36aa0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
36ab0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
36ac0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
36ad0 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
36ae0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
36af0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
36b00 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
36b10 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
36b20 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
36b30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
36b40 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
36b50 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
36b60 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
36b70 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
36b80 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
36b90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36ba0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
36bb0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36bd0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36be0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36bf0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36c00 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36c10 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
36c20 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
36c30 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
36c40 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
36c50 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
36c60 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
36c70 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
36c80 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
36c90 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
36ca0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
36cb0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
36cc0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
36cd0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
36ce0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
36cf0 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
36d00 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
36d10 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
36d20 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
36d30 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
36d40 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
36d50 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
36d60 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
36d70 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
36d80 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
36d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
36da0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
36db0 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
36dc0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36dd0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36de0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
36df0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
36e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
36e10 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
36e20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
36e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36e40 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
36e50 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
36e60 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
36e70 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
36e80 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
36e90 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
36ea0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
36eb0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
36ec0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
36ed0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
36ee0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
36ef0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
36f00 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
36f10 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
36f20 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
36f30 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
36f40 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
36f50 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
36f60 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
36f70 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
36f80 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
36f90 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
36fa0 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
36fb0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
36fc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
36fd0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
36fe0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
36ff0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
37000 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
37010 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37020 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37030 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
37040 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
37050 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37060 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37070 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37080 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37090 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
370a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
370b0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
370c0 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
370d0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
370e0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
370f0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
37100 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  phs..*/.SQLITE_A
37110 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
37120 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
37130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
37140 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
37150 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
37160 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
37170 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
37180 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
37190 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
371a0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
371b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
371c0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
371d0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
371e0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
371f0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
37200 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
37210 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
37220 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
37230 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
37240 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
37250 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
37260 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
37270 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
37280 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
37290 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
372a0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
372b0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
372c0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
372d0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
372e0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
372f0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
37300 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
37310 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
37320 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
37330 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
37340 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
37350 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
37360 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
37370 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
37380 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
37390 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
373a0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
373b0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
373c0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
373d0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
373e0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
373f0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
37400 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
37410 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
37420 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
37430 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
37440 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
37450 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
37460 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
37470 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
37480 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
37490 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
374a0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
374b0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
374c0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
374d0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
374e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
374f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
37500 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
37510 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
37520 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
37530 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
37540 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
37550 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
37560 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
37570 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
37580 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37590 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
375a0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
375b0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
375c0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
375d0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
375e0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
375f0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
37600 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
37610 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
37620 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
37630 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
37640 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
37650 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
37660 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37670 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
37680 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
37690 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
376a0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
376b0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
376c0 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
376d0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
376e0 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
376f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37700 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
37710 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
37720 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
37730 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
37740 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
37750 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
37760 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37770 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
37780 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
37790 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
377a0 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
377b0 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
377c0 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
377d0 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
377e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
377f0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
37800 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
37810 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37820 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
37830 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
37840 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
37850 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
37860 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
37870 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
37880 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
37890 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
378a0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
378b0 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
378c0 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
378d0 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
378e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
378f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
37900 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
37910 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
37920 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
37930 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
37940 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
37950 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
37960 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
37970 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
37980 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
37990 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
379a0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
379b0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
379c0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
379d0 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
379e0 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
379f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
37a00 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
37a10 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
37a20 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
37a30 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
37a40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
37a50 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
37a60 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
37a70 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
37a80 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
37a90 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
37aa0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  I int sqlite3_ge
37ab0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
37ac0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
37ad0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
37ae0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
37af0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
37b00 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
37b10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
37b20 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
37b30 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
37b40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37b50 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
37b60 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
37b70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
37b80 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
37b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37ba0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
37bb0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
37bc0 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
37bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37be0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
37bf0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37c00 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
37c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
37c20 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
37c30 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
37c40 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
37c50 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
37c60 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
37c70 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49  t place..*/.SQLI
37c80 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
37c90 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
37ca0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
37cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37cc0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
37cd0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37ce0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
37cf0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37d00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37d10 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
37d20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
37d30 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
37d40 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37d50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37d60 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
37d70 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
37d80 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
37d90 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
37da0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
37db0 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
37dc0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
37dd0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
37de0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37df0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
37e00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37e10 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
37e20 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
37e30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
37e40 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
37e50 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
37e60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37e70 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
37e80 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
37e90 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
37ea0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
37eb0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
37ec0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
37ed0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
37ee0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
37ef0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
37f00 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
37f10 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
37f20 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
37f30 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
37f40 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
37f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37f60 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
37f70 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
37f80 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
37f90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37fa0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
37fb0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37fc0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
37fd0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37fe0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37ff0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
38000 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
38010 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
38020 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
38030 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
38040 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
38050 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
38060 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
38070 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
38080 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
38090 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
380a0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
380b0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
380c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
380d0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
380e0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
380f0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
38100 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
38110 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
38120 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
38130 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
38140 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
38150 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
38160 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
38170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
38180 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
38190 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
381a0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
381b0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
381c0 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
381d0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
381e0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
381f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
38200 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
38210 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
38220 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
38230 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
38240 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
38250 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
38260 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
38270 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
38280 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
38290 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
382a0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
382b0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
382c0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
382d0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
382e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
382f0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
38300 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
38310 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
38320 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
38330 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
38340 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
38350 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
38360 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
38370 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
38380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
38390 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
383a0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
383b0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
383c0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
383d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
383e0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
383f0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
38400 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
38410 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
38420 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
38430 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
38440 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
38450 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
38460 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
38470 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
38480 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
38490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
384a0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
384b0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
384c0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
384d0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
384e0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
384f0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
38500 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
38510 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
38520 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
38530 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
38540 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
38550 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
38560 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
38570 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
38580 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
38590 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
385a0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
385b0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
385c0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
385d0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
385e0 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
385f0 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
38600 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
38610 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
38620 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
38630 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
38640 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
38650 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
38660 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
38670 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
38680 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
38690 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
386a0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
386b0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
386c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
386d0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
386e0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
386f0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
38700 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
38710 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
38720 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
38730 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
38740 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
38750 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
38760 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
38770 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
38780 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
38790 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
387a0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
387b0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
387c0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
387d0 6